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MANUAL  OBJECTIVES 

The  lAS/RSX-l  1  System  Library  Routines  Reference  Manual  descrihes  the 
usage  and  function  of  the  system  library  routines  that  may  be  called 
from  MACRO-11  assembly  language  programs. 


INTENDED  AUDIENCE 

This  manual  is  intended   for   use   by   experienced   MACRO-11   assembly 
language  programmers. 


STRUCTURE  OF  THIS  DOCUMENT 

Chapter  1  presents  -.   general  description  of  the  services   provided   bv 
the  system  library  routines  and  their  functional  relat ionsh Ids. 

Ci,~pter  2  describes  the  usage  and  function  of   the   register   handlinq 
routines. 

Chapter  3  describes  the  usage  and  function  of  the  arithmetic  routines. 

Chapter   4   describes   the   usage   and   function   of   the   input   data 
conversion  routines. 

Chapter  5   describes   the   usage   and   function   of    he   output   data 
conversion  routines. 

Chapter  6  describes  the  usage  and  function  of   the   output   formattinq 
routines. 

Chapter  7  describes  the  usage   and   function   of   the   dynamic   memory 
management  routines. 

Chapter  8  describes  the  usage   and   function   of   the   virtual   memory 
management  routines. 

Chapter  9  summarizes  the   calling   sequences   of   the   system   library 
rout  ines. 

Appendix  A  presents  a  cross-reference   system   bibliography   of   other 
manuals  that  describe  routines  available  to  IAS/RSX-11  systems  users. 

Appendix  B  describes  a  routine  that  allows  a  program  to  access  modules 
in  a  univorsal  library  as  if  they  were  files. 
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ASSOCIATED  DOCUMENTS 

The  following  manuals  are  prereauisite   sources  of   information   for 
readers  of  this  manual: 

•  -AS/RSX-U  MACRO-11  Reference  Manual. 

•  The  Task  Builder  Reference  Manual  for  the  appropriate  syster. 

•  The  manuals  referenced  in  Appendix  A. 

The  reader  should  refer  to  the  applicable  documentation  directory   for 
descriptions  of  other  documents  associated  with  this  manual. 
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CHAPTER  1 
INTRODUCTION 


The  routines  described  in  this  manual  were  written  to  provide  commonly 
needed  capabilities  for  DIGITAL-suppl ied  utiiitier.  we  are  hapov  to 
supply  docuF'^ntat ion  for  thorn,  because  the  routinei3  are  general  enouah 
to  be  used  regularly  by  most  MACRO-11  programmers.  Note,  however, 
that  the  basic  functionality  of  the  routines  described  in  this  manual 
cannot  be  changed,  due  to  the  potentially  widespread  effect  it  mav 
have  on  our  system  utilities. 

The  system  library  routines  may  be  called  by  MACRO-11  assembly 
language  programs  to  perform  the  following  services: 

•  Save  and  restore  re^jister  content  to  enable  transfers  of 
control  between  tha  calling  program  and  called  subroutines. 

•  Perform  integer  and  double-pi ecision  multiplication  and 
division, 

•  Convert  ASCII  input  data  to  internal  binary  and  Radix-50 
format. 

•  Convert  internal  binary  and  Radix-50  data  to  ASCII  output 
data. 

•  Convert  and  format  output  data  to  produce  text  for  a  readable 
printout  or  display. 

•  Manage  the  dynamic  memory  space  available  to  the  task  that 
requires  a  small-to-moderate  amount  of  resident  memory  for 
data . 

•  Manage  memory  and  disk  file  storage  to  accommodate  tasks  that 
require  1 irge  amounts  of  memory  for  data  that  must  be 
transL.'rred  between  memory  and  a  disk  work  file. 

This  manual  describes  the  procedures  for  calling  the  library  routines 
from  within  the  source  program,  the  outputs  that  are  returned  to  the 
executing  task,  and  the  interaction  between  the  library  routines  and 
the  executing  task. 

The  system  library  routines  interface  with  each  other  to  perform  their 
various  services.  For  example,  the  data  conversion  routines  call  the 
arithmetic  routines  to  perform  the  required  multiplication  anc: 
division.  All  library  rout-ines  preserve  the  contents  of  the  calling 
task's   registers,   generally  by   calling   the   appropriate   register 
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•  Push  register  contents  to  the  stack, 

•  Subsequently  pop  the  conlents  back  into  the  registers. 

•  Return  control  to  the  calling  task. 

The  data  conversion  and  format  control  functions  performed  by  the  I-'dit 
Message  Routine  require  calls  to  the  output  data  conversion  routines, 
which  in  turn  call  other  routines. 

The  virtual  memory  manaqement  routines  function  as  an  automatic 
control  system  to  allocate  and  deallocate  memory,  maintain  page 
addresses  and  status,  and  swap  pages  between  memory  and  disk  storage 
to  accommodate  large  amounts  of  data  in  c  limited  amount  of  physical 
(dynamic)  memory.  » 

The  system  library  routines  communicate  with  the  calling  task  via 
registers  in  which  outputs  are  returned  and/or  settings  of  the  C  bit 
in  the  Condition  Code  of  the  Processor  Status  Word.  The  calling  task 
can  usually  determine  whether  a  requested  service  was  successfully 
performed  by  exami..ing  the  output  register  (s)  and/or  testing  the  C  bit 
setting  when  control  is  returned  from  the  library  routine.  Exceptions 
to  this  procedure  are  described  in  the  detailed  discussions  of  given 
rout  ines. 


The  system  liorary  routines  are  supplied  to  users  as   object   code 
two  files: 
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The  system   library   file   (SYSLIB.OLB) ,   which   contains   the 
fol lowing : 

the  register  handling  routines,  described  in  Chapter  2. 

the  arithmetic  routines,  described  in  Chapter  3. 

the  input  and  output  data  conversion  routines,   described 
in  Chapter  4  and  Chapter  'J . 

the  output  formatting  routines,  described  in  Chanter  6. 

the   dynamic   memory   allocation   and   release    routines 
descriibed  in  Chapter  7. 

the   universal   library   access   routines   described    in 
Appendix  B. 

•  The   memory   management   routines   file    (VMLIP.Or.B)  ,    which 
contains  the  dynamic  and  virtual  memory  manaqement  routines. 

At  task  build  time,  the  "ask  Builder  will  automat ical Iv  search  the 
system  library  file  for  any  referenced  routines.  However,  the 
VMLIB.OLB  file  must  be  specified  at  task  build  time  if  a  task  has 
referenced  the  dynamic  memory  initialization  routine  described  in 
Chapter  7,  cr  any  of  the  virtual  memory  management  routines,  described 
in  Chapter  8  of  this  manual. 

Summarized  procedures  for  using  the  system  library  routines  are 
presented,  in  tabular  format,  in  Chapter  9.  This  is  quick-reference 
material,  provided  for  the  MACPO-11  assembly  language  programmer  who 
has  berome  familiar  with  the  de' ailed  procedures  tha^  are  explained  in 
Chapter?  2  through  A   of  this  manual. 

Additional  Executive  and  I/O  routines  available  to  IAS/RSX-11  systems 
users   are    described    in   other   manuals.    The   System   Reference 
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Bibliography  in  Appendix  A  prerents  a  cross-reference  listing  of  these 
manual  titles,  and  functional  desc-r  iptions  of  types  of  services 
described  in  the  respective  manual. 
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Tcble  1-1 
Program  Section  Names  for  SYSLIB  Routines 


Program 
Section 

SYSLIB  Routines 

Module 

Routine 

Name 

Name 

Name  (s) 

.  ELK. 

CATB 

SCDTB 
$COTB 

CATS 

$CAT5 

CAT5B 

$CAT5B 

CBTA 

$CBDAT 

$CBDMG 

$CBDSG 

$CBOMG 

SCBOSG 

SCBTA 

SCBTMG 

CDDMG 

SCDDMG 

CVTUC 

SCVTUC 

C5TA 

SCSTA 

EDDAT 

SDAT 
STIM 

EDTMG 

SEDMSG 

OD.:CT 

.DD2CT 
.0D2CT 

SAV;*L 

SSAVAL 

SAWR 

SSAWR 

$$RESL 

SAvRG 

SSAVRG 

SAVRl 

.SAVRl 

$$RESM 

ARITH 

SDIV 
SMUL 

DARITH 

SDDIV 

:;DMt)L 
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CHAPTER  2 
REGISTER  HANDLING  ROUTINES 

There  are  four  register  handling  routines  in  the  system  library: 

•  Save  All  Registers  Routine  (?SAVAL),  which  saves  and 
subsequently  restores  registers  0-5,  as  described  in 
Section  2.1. 

•  Save  Registers  3-5  Routine  (SSAVRG) ,  which  saves  and 
subsequently  restores  registers  3-5,  as  described  in 
Section  2.2. 

•  Save  Registers  0-2  Routine  ($SAVVR),  which  saves  and 
subsequently  restores  registers  0-2,  as  described  in 
Section  2.3. 

•  Save  Registers  1-5  Routine  (.SAVRl),  which  saves  and 
subseque'  tly  restores  registers  1-5,  as  described  ir 
Section  2.4. 

The  register  handling  routines  function  as  co-routines  to  enable 
control  swapping  between  themselves,  a  subroutine,  and  the  original 
caller  of  the  subroutine. 

To  illustrate  the  effect  of  using  the  register  handling  routines, 
assume  the  following:  an  or  .ginal  caller  calls  a  subroutine.  The 
subroutine  calls  a  register  handling  co-routine.  The  co-routine 
pushes  the  contents  of  the  specified  registers  to  the  stack,  and 
issues  a  co-routine  call  back  to  the  subroutine.  The  subroutine 
executes  to  completion,  then  a  RETURN  instruction  is  executed  to  swao 
control  back  to  the  co-routine.  The  co-routine  poos  the  initial 
contents  of  the  registers  from  the  stack  and  returns  to  the  oriqinal 
caller . 

Figure  2-1  illustrates  the  control  swapping  function  performed  by  the 
register  handling  routines. 

The  register  handling  routines  are  called  by  other  routines  in  the 
system  library,  as  noted  throughout  this  document. 
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$SAVAL     SAVE  ALL  REGISTERS 


ORIGINAL  CALLER 
START 


L«gend 

CALL  (uibroutin*)  •  JSR  PC.  lubroutin* 
RETURN  -RTSPC 


CALL  (Subroutine)  ' 


MSubroutint) 

JSR  r,$SAV«x 


RETURN- 


END 


-•■  SSAVmk  |mv<  fcgiittri) 


I  (iitiM  coroutin*  call 
I        (o  lubroudna) 


(restore  rsgitttrti 


RETURN  (to  origin«l  callRrI 


Figure  2-1   Control  Swapping  of  the  Register  Handling  Routines 


2.1   SAVE  ALL  REGISTERS  ROUTINE  ($SAVAL) 

The  $SAVAL  routine  saves  and  subsequently  restores  registers  0-5  for 
a  subroutine.  The  SSAVAL  routine  functions  as  a  co-routine  which 
swaps  control  between  itself,  a  subroutine,  and  the  original  cailer. 

To  call  the  $SAVAL  routine,  the  subroutine  must  contain  the  following 
Jump  to  Subroutine  instruction: 

JSR   PC, SSAVAL 

The  subroutine  must  return  control  to  the  SSAVAL  routine  with  a  RETURN 
source  statement. 

On  entry  to  the  SSAVAL  routine,  the  progiam  stack  contains  the  return 
address  to  the  original  caller  and  the  return  address  of  the 
subroutine.  The  SSAVAL  routine  pushes  the  contents  of  registers  4-0 
to  the  stack. 

The  SSAVAL  routine  moves  the  subroutine's  return  address  the 
position  following  Register  O's  contents,  and  moves  the  cj.rent 
contents  of  R5  to  the  stack  above  the  contents  of  R4 . 

The  SSAVAL  routine  issues  a  co-routine  call,  in  the  form  CALL  ?(SP)+, 
to  swap  control  back  to  the  subroutine.  The  co-routine  call  replaces 
the  subroutine's  return  address  with  the  return  address  to  the  SSAVAL 
routine.  When  control  returns  to  the  subroutine  the  stack  pointer 
points  to  SSAVAL's  return  address.   The  stack  contains  the  following; 
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SAVE  ALL  REGISTERS      $SAVAL 
SAVE  REGISTERS  3  6         $SAVRG 


Return  Address  to  Original  Caller 


Register  5 


Register  4 


Register  3 


Register  2 


Register  1 


xegister  0 


Return  Address  to  5SAVAL 


The  subroutine  executes  until  a  RETURN  (  '  RTS  PC)  instruction  is 
executed,  which  swaps  control  back  to  the  SSAVAL  routine.  The 
contents  of  RO  -  R5  are  restored  (popped  from  the  stack)  and  the 
SSAVAL  routine  RETURNS,  via  an  'RTS  PC  instruction,  to  the  oriqinal 
caller. 


NOTE 


For  SSAVAL  to  work 
return  control  to 
the  routine  that 
itself  have  been 
instruction  (that 
subroutine) . 


properly   (that   is, 

the  oriqinal  caller), 

calls   SSAVAL    must 

invoked   by  the  CALL 

is,     JSP     PC, 


2.2   SAVE  REGISTERS  3-5  ROt'TINE  (SSAVRG) 

The  SSAVRG  routine  saves  and  subsequently  restores  reqisters  3-5  for 
a  subroutine.  The  SSAVRG  routine  functions  as  a  co-routine  which 
swaps  control  between  itself,  a  subroutine,  and  the  oriqinal  caller. 

To  call  the  SSAVRG  routine,  the  subroutine  must  contain  the  followlnq 
Jump  to  Subroutine  Instruction: 

JSR  R5,$SAVRG 

The  subroutine  must  return  control  to  the  SSAVRG  routine  with  a  RETURN 
source  statement. 

On  entry  to  the  SSAVRG  routine,  the  proqram  stack  contains  the  return 
address  to  the  original  caller  and  the  contents  of  R5  of  the  orloinal 
caller.  The  SSAVRG  routine  pushes  the  contents  of  reqisters  4  and  3 
to  the  stack,  then  pushes  the  current  contents  of  R5  (return  address 
to  the  subroutine)  to  the  stack. 

The  SSAVRG  routine  copies  the  original  contents  back  into  R5  ind 
Issues   a   co-routine   call.   In  the  form  CALL  ?(SP)+,  to  swap  control 
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$SAVRG      SAVE  REGISTERS  3-5 
$SAVVR       SAVE  REGISTERS  0-2 


back  to  the  subroutine.  The  co-routine  call  replaces  the  subroutine's 
return  address  with  the  return  address  to  the  SSAVRG  routine.  when 
control  returns  to  the  subroutine,  the  stack  pointer  points  to 
$SAVRG's  return  address.   The  stack  contains  the  followinq; 


Return  Addresi  to  Original  Caller 


Register  5  contents  of  Original  Caller 


Register  4 


Register  3 


Return  Address  to  SSAVRG 


The  subroutine  executes  until  a  RETURN  ('RTS  PC)  instruction  is 
executed,  which  swaps  control  back  to  the  SSAVRG  routii.e.  The 
contents  of  registers  3-5  are  restored  (popped  from  the  stack)  an'i 
trie  SSAVRG  routine  RETURNS,  via  an  'RTS  PC  instruction,  to  the 
original  caller. 

NOTE 

For  SSAVRG  to  work  properly  (that  is, 
return  control  to  the  original  caller), 
the  routine  that  calls  SSAVRG  must 
itself  have  been  invoked  by  the  CALL 
instruction  (that  is,  JSR  PC, 
subroutine) . 


2.3   SAVE  REGISTERS  0-2  ROUTINE  (SSAWR) 

The  S3AVVR  routine  saves  and  subseauently  restores  registers  0-2  for 
a  subroutine.  The  SSA'/^/R  routine  functions  aa  a  co-routine  which 
swaps  control  between  itself,  a    subroutine,  and  the  orialnal  caller. 

To  call  the  SSAWR  routine,  the  subroutine  must  contain  the  followir  i 
Jump  to  Subroutine  insttuction: 

JSR  R2,  SSAWR 

The  subroutine  must  return  control  to  the  SSAWR  routine  with  «  PFTURV 
source  statement. 

On  entry  to  the  SSAWR  routine,  the  proaram  stack  contains  the  return 
address  to  the  original  caller  and  th.-  contents  of  R2  of  the  oriqinal 
caller.  The  SSAWR  routine  pujhes  the  contents  of  reqiste'S  1  and  0 
to  the  stack,  then  pusher  the  current  contents  of  R2  (the  return 
address  to  the  subroutine)  to  the  stack. 

The  SSAWR  routine  copies  the  original  contents  back  into  R2  and 
issues  a  co-routine  call,  in  the  form  CALL  iJ(SP)+,  to  swap  control 
back  to  the  subroutine.  The  co-routine  call  replaces  the  subroutine's 
return  ^  •idress  with  the  return  address  to  the  SS/'.WR  routine.  when 
control  returns  to  the  subroutine,  the  stack  pointer  points  to 
SSAWR's  return  address.   The  stack  contains  the  followinq: 
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SAVE  REGISTERS  >2      $SAVVR 
SAVE  REGISTERS  15     .»SAVR1 


R'^turn  AddredS  to  Original  Caller 


Register  2  contents  of  Original  Caller 


Register  1 


Register  0 


Return  Address  to  $SAV7R 


The  subroutine  executes  until  a  RETURN  ('RTS  PC)  instruction  is 
executed,  which  swaps  control  back  to  the  $SAVVR  routine.  The 
contents  of  registers  0-2  are  restored  (popped  from  the  stack)  and 
the  $SAVVR  routine  RETURNS,  via  an  'RTS  PC  instruction,  to  the 
original  caller. 


NOTE 

For  $SAWR  to  work  properly  (that  is, 
return  control  to  the  original  caller), 
the  routine  that  calls  $SAWR  must 
itself  have  been  invoked  by  the  CALL 
instruction  (that  is,  JSR  PC, 
subroutine) . 


2.4   SAVE  REGISTERS  1-5  RODTINE  (.SAVRl) 

The  .SAVRl  routine  saves  and  subsequently  restores  reaisters  1-5  for 
a  subroutine.  The  .SAVRl  routine  functions  as  a  co-routine  which 
swaps  control  between  itself,  a  subroutine,  and  the  original  caller. 

To  call  the  SAVRl  routine,  the  subroutine  must  contain  the  following 
Jump  to  Subr -iitine  instruction: 

JSR  R5, .PAVRl 

The  subroutine  must  return  control  to  the 
source  statement. 


.SAVRl  routine  with  a  RETURN 


On  antry  to  the  .SAVRl  routine,  the  program  stack  contains  the  return 
address  to  the  original  caller  and  the  contents  of  R5  of  the  original 
caller.  T''e  .SAVRl  routine  pushes  the  contents  of  registers  4,  3,  2, 
end  1,  a  the  current  contents  of  R5  (the  return  address  to  the 
subroutine)  to  the  stack. 

The  .SAVRl  routine  copies  the  original  contents  back  into  R5  and 
issues  a  co-ioutine  call,  in  the  form  CALL  0(SP)+,  to  swap  control 
back  to  the  subroutine.  The  co-routine  call  replaces  the  subroutine's 
return  address  with  the  return  address  to  the  .SAVRl  routine.  When 
control  returns  to  the  subroutine,  the  stack  pointer  points  to 
.SAVRl's  return  address.  Ine   stack  contains  the  following: 
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•  SAVR1      SAVE  REGISTERS  16 


Return  Address  to  Original  Caller 


Register  5  contents  of  Original  Caller 


Register  4 


Register  3 


Register  2 


Register  1 


Return  Address  to  .SAVRl 


The  subroutine  executes  until  a  RETURN  ('RTS  PC)  instruction  is 
executed,  which  swaps  control  back  to  the  .SAVRl  routine.  The 
contents  of  registers  1-5  are  restored  (popped  from  the  stack)  and 
the  .SAVRl  routine  RETURNS,  via  an  'RTS  PC'  instruction,  to  the 
original  caller. 


NOTE 


For  .SAVRl  to  work 
return  control  to 
the  routine  that 
itself  have  been 
instruction  (that 
subroutine) . 


properly   (that   is, 

the  original  caller), 

calls   .SAVRl    must 

invoked   by  the  CALL 

is,     JSR     PC, 
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CHAPTER  3 
ARITHMETIC  ROUTINES 


The  system  library  contains  four  arithmetic  routines  that  perform 
unsigned  integer  multiplication  and  div^ision.  This  chapter  describes 
the  usage  and  function  of  tnese  arithmetic  routines. 


3.1   INTEGER  ARITHMETIC  ROUTINES 

The  system  library  contains   two   routines   which   perform   arithmetic 
operations  on  lb-bit  unsigned  integer  values: 

•  The  Integer  Multiply  Routine  (SMUL) ,  which  multiplies   integer 
values . 

•  The  Integ'er   Divide   Routine   (5DIV)  ,   which   divides   integer 
values. 

The  usage  of  tnese   roucines   is   described   and   illustrated   in   the 
following  paragraphs. 


3.1.1   Integer  Multiply  Routine  ($MUL) 

The  $MUL  routine  multiplies  two   single-word   unsigned   integer   input 
values  to  produce  an  unsigned  double-word  product. 

To  call  the  $MUL  routine: 

•  Specify  two  input  arguments: 

•  in  Register  0,  the  multiplier. 

•  in  Register  1,  the  multiplicand. 

•  Include  the  statement 

CALL  SMUL 
in  the  source  program. 
Registers  2  -  5  of  the  calling  task  are  preserved. 
The  output  fr^m  the  SMUL  routine  is: 

•  RO  =  high  order  part  of  result. 

•  Rl  =  low  order  part  of  result. 

The  SMUL  routine  does  not  return  any  error  indications  to  the  caller. 
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3.1.2   Integer  Divide  Routine  (SDIV) 

The  ;?DIV  routine  performs  unsigned  integer  division. 

To  call  the  $DIV  routine: 

•  Specify  two  input  arguments: 

•  in  Register  U,  the  dividend. 

•  in  Register  1,  the  divisor. 

•  Include  the  statement 

CALL  $DIV 
in  the  source  program. 
Registers  2  -  5  of  the  calling  task  are  preserved. 
The  output  from  the  $DIV  routine  is: 

•  RO  =  quotient. 

•  Rl  =  the  remainder. 

The  $DIV  routine  does  not  return  any  error  indications  to  the  caller. 

3  . 1 .  J   ;^xample 

The  following  source  statements   call   the   $MUL   routine   to   perform 
multiplication  and  store  the  results. 


MOV 

11200, RO 

MOV 

NDV,R1 

CALL 

$MUL 

MOV 

R0,WORK 

MOV 

Rl,W0RK-t-2 

PUTS  MULTIPLIER  IN  RO. 

P'JTS  THE  MULTIPLICAND  AT  NDV  IN  Rl. 

CALLS  SMUL  ROUTINE. 

STORES  HIGH  ORDER  PART  OF  RESULT  IN  WORK, 

STORES  LOW  ORDER  PART  OF  RESULT  !N 

WORK +2. 


(continue) 


3.2   DOUBLE-PRECISION  ARITHMETIC  ROUTINES 

There  are  two  double-precision   integer   arithmetic   routines   in   the 
system  library: 

•   The   Double-precision   Multiply    Routine  (SDMUL),    which 

multiplies    an    unsigned    double-precision  value    by    a 

single-precision  multiplier   to   produce  a  double-precision 
product . 
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•      The    Double-precision   Divide    Routine    ($DDIV) ,    which   divides      an 
unsigned  double-precision  dividend  by        an        unsigned 

single-precision   divisor    to    produce   a   double-precision    result. 

The    usage   of    these      routines      Is      described      and      illustrated      in      the 
following    paragraphs. 


3.2.1  Doubla-PrecUion   Multiply    Routine    (SDMUL) 

The  SDMUL  routine  multiplies  an  unsigned  double-precision  value  by  a 
single-precision  value  to  produce  an  unsigned  double-precision 
product. 

To    call    thr.    eoM'JL    routine: 

•  Specify   two    input    arguments: 

•  in    Reglstri'    0,    the    single-precision   magnitude   multipli'-r. 

•  the   double-precision   magnitude   multiplicand,    where: 

•  Register    2    contains    the    high   order    part. 

•  Register    3    contains    the    low  order    part. 

•  Include    the    statement 

CALL    SDMUl 

In  the  source  program. 

Registers  4  and  5  of  the  calling  task  are  preserved.  Registers  2  and 
3  are  destroyed  on  return  to  the  calling  task. 

The  outputs  from  the  SDMUL  routine  are: 

•  The  double-precision  magnitude  product,  where: 

•  RO  »  high  order  part. 

•  Rl  =  low  order  part. 

The  SDMUL  routine  does  not  return  any  error  indications  to  the  caller. 

3.2.2  Double-Precision  Divide  Routine  (SDDIV) 

The   SPDIV   routine   divides   an   unsigned   double-precision    integer 
dividend   by   an  unsigned  single-precision  (15-blt)  divisor  to  produce   | 
an  unsigned  double-precision  result. 

To  call  the  SDDIV  routine: 

•  Specify  two  input  arguments: 

•  in  Register  0,  the  unsigned  divisor. 

•  the  double-precision  dividend,  where: 

•  Register  1  contains  the  high  order  part. 

•  f'.egister  2  contains  the  low  order  part. 
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•  Include  the  statement 

CALL  SDUIV 

in  the  source  pcogram. 

The  content  of  Register  J  ot  the  calling  task  is  saved   and   restored, 
Registers  4  and  5  are  not  jsed. 

The  outputs  from  the  SDDIV  routine  are: 

•  RO  *  remainder . 

•  Quotient,  where: 

•  Rl  «  high  order  pat t  of  quotient. 

•  R2  -  low  order  part  of  quotient. 

The  SDDIV  routine  does  not  return  any  error  indications  to  the  caller. 


3.2.3   Example 

The  following  source  statements  call 
division  and  store  the  results. 


the   SDDIV   routine   to   perform 


MOV 
MOV 


♦150, RO 
DVD.Rl 


MOV  DVDf2,R2 

CALL  SDDIV 

MOV  R1,QU0T 

MOV  R2,QUOT-)-2 

MOV  RO,RMAIN 


PUTS  DIVISOR  IN  RO. 

PUTS  THE  HIGH  ORDER  PART  OF  THE  DIVID- 
END, STORED  IN  DVD,  IN  Rl. 
PUTS  LOW  ORDER  PART  OF    DIVIDEND,  STORED 
IN  DVD*2,  IN  rN2. 
CALLS  SDDIV  ROUTINE. 

PUTS  HIGH  ORDER  PART  OF  QUOTIENT  IN  QUOT . 
PUTS  LOW  ORDER  PART  OF  QUOTIENT  IN  QU0T*2. 
PUTS  REMAINDER  IN  REMAIN, 


(continue) 
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CHAPTER  4 
INPUT  DATA  CONVERSION  ROUTINES 


The  system  library  input  data  conversior:  routines  accept  ASCII  data  as 
input  and  convert  it  to  tts  specified  numeric  representation.  There 
are  three  types  of  routines  that  perform  input  data  conversion: 

•  ASCII  to  binary  double-word  conversion  routines,  which  accept 
ASCII  decimal  or  octal  input  numbers  and  convert  them  to 
double-word  binary  numbers,  as  described  in  Section  4.1  of 
this  chapter . 

•  ASCII  to  binary  conversion  routines,  which  accept  ASCII 
cecimal  or  octal  input  numbers  and  convert  them  to  sinqle-word 
binary  numbers,  as  descriDed  in  Section  4.2. 

•  ASCII  to  Radix-bG  conversion  routines,  which  accept  ASCII 
alphanumeric  input  characters  and  convert  them  to  Radix-50 
internal  format,  as  described  in  Section  4.3. 


4.1   ASCII  TO  BINARY  DOUBLE-WORD  CONVERSIONS 

There  aie  two  syste.ii  iiorary  routines  that  convert  ASCII  input  numbers 
to  double-word  binary  numbers: 

•  The  Decimal  to  Binary  Double-word  Routine  (.DD2CT),  which 
accepts  ASCII  deci;nal  numbers  as  input,  and  converts  them  to 
double-word  binary  format,  described  in  Section  4.1.1. 

•  The  Octal  to  Binary  Double-word  Routine  ( .0D2CT) ,  which 
accepts  ASCII  octal  numbers  as  input  and  converts  them  to 
double-word  binary  format,  described  m  Section  4.1.2. 


4.1.1   Decimal  to  Binary  Double-word  Routine  (.DD2CT) 

The  .DD2CT  routine  converts  a  signed  ASCII  decimal  number  string  to  a 
double  length  (two-word)  signed  binary  number. 

The-  routine  accepts  leading  plus  (♦)  or  minus  (-)  signs,  and  a 
trailing  decimal  point.  A  preceding  t  symbol  is  acceptable,  but  will 
force  octal  conversion.  ^  ♦  symbol  and  a  period  in  the  same  input 
string  is  invalid.  Acceptable  characters  in  the  string  are  the 
numbers  0  -  y.  Any  other  characters  in  the  string  will  cause  the 
.DD2CT  routine  to  terminate  the  conversion  procedure.  The  value  range 
of  a  decimal  number  to  be  converted  is  -231   to  *2^^     -1. 
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To  call  the  .DD2CT  routine: 

•  Supply  three  input  ar-juments  in  the  task's  source  code: 

•  in  Register  3,  the  address  of  the  two-word  field  in  which 
the  converted  number  is  to  be  stored. 

•  in  Register  4,  the  number  of  characters  in  the  string   to 
be  converted. 

•  in  Register  5,  the  address  of  the  character  string  to   be 
converted . 

•  Include  the  statement 

CALL  .DD2CT 

in  the  source  program. 

The  .DD2CT  routine  saves   and   restores   all   of   the   calling   task's 
registers.   Outputs  from  the  .DD2CT  routine  are: 

•  The  converted  number,  where  the  high  order  16  bits  are  stored 
in  word  1  of  the  field  specified  in  R3  input,  and  the  low 
order  16  bits  are  stored  in  word  2  of  the  field. 

•  Condition  Code: 

C  bit  =  clear  if  conversion  was  successful. 

C  bit  =  set  if  an  illegal  character  was  found   and   conversion 
was  incomplete. 

The  user  can  determine,  in  the  task,  whether  conversion   was   complete 
by  testing  the  C  bit  in  the  Condition  Code. 


4.1.2   Octal  to  Binary  Double-word  Routine  (.0D2CT 

The  .0D2CT  routine  converts  an  ASCII  octal  number  string  to  a  double 
length  (two-woid)  binary  number. 

The  routine  accepts  loading  plus  (+)  or  minus  (-)  signs,  and  the 
numbt-rs  0-7.  A  preceding  #  symbol,  is  legal  in  the  octal  number 
string.  A  #  symbol  and  a  period  in  the  same  input  string  is  invalid. 
A  trailing  decimal  point  will  be  accepted  in  the  input  string,  but 
will  cause  the  decimal,  rather  than  octal,  radix  to  be  used.  This 
condition  exists  because  the  .0D2CT  routine  is  an  entry  point  in  the 
.DD2CT  routine,  which  converts  decimal  number  strings  to  binary 
double-word  values  (see  Section  4.1.1). 

Any  other  characters  in  the  ASCII  octal  number  spring  will  cause  the 
.0D2CT  routine  to  terminate  the  conversion  procedure. 

The  value  range  of  an  octal  number  to  be  converted  is  -2  to 
+231   _i. 
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To  call  the  .0D2CT  routinei 


•  Supply  three  input  arguments  in  the  task's  source  code; 

•  in  Register  3,  the  address  of  the  two-word  field  in  which 
the  converted  number  is  to  be  stored. 

•  in  Register  4   the  number  of  characr.ers  in  the  string   to 
be  converted. 

•  in  Register  5,  the  address  of  the  character  string  to  be 
converted. 

•  Include  the  statement 

CALL  .0D2CT 

in  the  source  program. 

The  .0D2CT  routine  saves   and   restores   all   of   the   calling   task's 
registers.   Outputs  from  the  .0D2CT  routine  are: 

•  The  converted  number,  where  the  high  order  16  bits  are  stored 
in  word  1  of  ths  field  specified  in  R3  input,  and  the  low 
order  16  bits  are  stored  i;-;  wo.d  2  of  the  field, 

•  Condition  C . .s: 

C  bit  =  clear  if  conversion  was  sjccessf^l. 

C  bit  =  set  if  an  illegal  chviracter  wc.s  found   and   conversion 
was  incomplete. 

The  user  can  oetermine,  in  the  task,  whether  conversion   was   complete 
by  testing  the  C  bit  in  the  Condition  Code. 


4 . 1 . J   Example 

The  following  soi;rce  statements  illustrate  a  way  of  calling  the  .0D2CT 
routine  and  checking  the  results  on  return. 


BOUT! 


.BLKW 


MOV 

#B0UT,R3 

MOV 

#7,R4 

MOV 

#ICHR,R5 

CALL 

.0D2CT 

BCS 

100$ 

(conti 

nue) 

PUTS  THE  ADDRESS  OF  THE  2-WORD  OUTPUT 

riELD  (BOUT)  IN  R3. 

PUTS  THE  NUMBER  7  (NUMBER  OF  INPUT 

CHARACTERS)  IN  R4. 

PUTS  THE  ADDRESS  OF  THE  INPUT  CHARACTER 

STRING  (ICHR)  IN  R5. 

CALLS  THE  .0D2CT  ROUTINE. 

BRANCHES  TO  100$  IF  C  BIT  SET  (INPUT  STRING 

CONVERSION  WAS  NOT  SUCCESSFUL). 

IF  C  BIT  CLEAR  CONVERSION  WAS  SUCCESSFUL 

AND  THE  PROGRAM  CONTINUES. 


100$! 


CALL  ERR 


;CALL  ERR  ROUTINE  TO  OUTPUT  MESSAGE, 
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4.2   ASCII  TO  BIKARY  CONVERSIONS 

There  are  two  system  library   routines   that   convex t   unsigned   ASCII 
input  numbers  to  single-word  unsic  led  binary  numbers: 

•  The  Decimal  to  Binary  Conversion  Routine  (SCDTB),  which 
accepts  ASCII  decimal  numbfrL  as  input  and  .'onverts  them  to 
single-word  binary  format,  described  in  Section  4.2.1. 

•  The  Octal  to  Binary  Conversion  Routine  (SCOTB),  which  accepts 
ASCII  octal  numbers  as  input  and  converts  them  to  single-word 
binary  format,  described  in  Section  4.2.2. 

These  routines  call  the  Integer  Multiply  Routine  (SMUL)  to  perform  the 
multiplication  required  for  the  conversion. 


4.2.1   Decimal  to  Binary  Conversion  Routine  ($rDTB) 

The  $CDTB  routine  converts  an  unsigned  ASCII  decimal  number  to  binary. 

Valid  characters  in  the  input  decimal  number  are  the  characters  0  -  9. 
All  other  input  characters  are  invalid  and  are  not  converted  by  this 
routine . 

The  eno  of  a  string  of  numbers  must  be  marked  by  a  terminating 
character,  which  may  be  any  ASCII  character  except  the  numbers  0-9. 
Examples  of  terminating  characters  are:  blank,  tab  character, 
alphabetic  character,  and  a  special  symbol.  Leading  blanks  and  tab 
characters  ar»  ignored. 

The  maximum  value  of  a  decimal  number  that  can  be  converted  by  the 
$CDTB  routine  is  65,535.  Numbers  of  greater  value  will  cause 
indeterminate  results,  since  the  SCDTB  routine  does  not  check  the 
value  rc.nge  of  an  inpuL  numbei*.  No  significant  condition  code  setting 
is  returned  to  the  calling  task. 

To  call  the  $CDTB  routine: 

•  Input,  in  Register  0,  the  address  of  the   first   byte   of   the 
ASCII  characters  to  be  converted. 

•  Include  the  statement 

CALL  $CDTB 

in  the  sjurce  program. 

The  $CDTB  routine  calls  the  $SAVRG  routine  to  save  and  restore 
registers  3  -  5  of  the  calling  task. 

The  outputs  returned  from  the  SCDTB  routine  are: 

•  RO  =  the  address  of  the  next  byte  in  the  input  buffer. 

•  Rl  =  the  converte<^  number. 

•  R2  =  the  terminating  cnar^cter. 

The  user  can  determine,  in  the  task,  whether  an  input  string  was 
successfully  converted  by  testing  the  content  of  R2.  It  the  content 
is  other  than  the  expected  termin.iting  character,  the  conversion  was 
incomplete,  since  some  other  invalid  character  was  found  in  the  input 
str  ing. 
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Since  the  $CDTB  routine  returns  the  address  of  the  next  byte  in  the 
input  buffer  to  the  calling  task,  successive  input  string  conversion 
may  be  effected  by  setting  up  a  processing  loop  back  to  the  CALL  SCDT8 
statement,  as  shown  in  Section  4.2.3. 


4.2.2  Octal  to  Binary  Conversion  Routine  (SCOTB) 

The  $COTB  routine  converts  an  ASCII  octal  number  to  binary.  Valid 
Characters  in  the  number  to  be  converted  are  0-7. 

The  end  of  a  string  must  be  marked  by  a  terminating  character,  which 
may  be  any  ASCII  character  except  the  numbers  0-7.  Examples  of 
terminating  characters  are:  blank,  a  tab  character,  an  alphabetic 
character,  and  a  special  symbol.  Leading  blanks  and  tab  characters 
are  ignored. 

The  maxim.um  value  of  an  octal  number  that  can  be  converted  by  the 
$COTB  routine  is  177777. 

To  call  the  SCOTB  routiner 

•  Input,  in  Register  0,  the  address  of  the   first   byte   of   the 
ASCII  characters  to  be  converted. 

•  Include  the  statement 

CALL  $COTB 

in  the  source  program. 

The  SCOTB  routine  calls  the  SSAVRG  routine  to  save  and  restore 
registers  3  -  5  of  the  calling  task. 

The  outputs  returned  from  the  5C0TB  routine  are: 

•  RU  =  the  address  of  the  next  byte  in  the  input  buffer. 

•  Rl  =  the  converted  number. 

•  R2  =  the  terminating  character. 

The  user  can  determine,  in  the  task,  whethei  an  input  string  was 
successfully  converted  by  testing  the  content  of  R2.  If  the  content 
is  other  than  the  expected  terminating  character,  the  conversion  was 
incomplete,  jince  some  other  invalid  character  was  found  in  the  input 
str  ing . 

Successive  input  string  conversion  may  be  effected  by  setting  up  a 
processing  loop  as  shown  in  the  example  for  the  SCDTB  routine  m 
Section  4.2.3. 


4.2.3   Example 

The  following  source  statements  define  a  processing  loop,  using  the 
$CDTB  routine,  to  convert  a  series  of  ASCII  decimal  character  strings 
to  binary  numbers.  The  character  strings  stored  in  the  input  buffer 
(IBUF)  are  in  the  format 

XXX (TAB) XX XX (TAB) xx (TAB) xxxxx (SPACE) 
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where  the  TAB  character  is  used  as  the  terminating  character  of  each 
string,  and  the  SPACE  character  is  used  as  the  terminating  character 
of  the  input  buffer.  If  converted  successfully,  the  binary  numbers 
are  to  be  stored  in  the  buffer,  BNUM. 

MOV   |BNUM,R4    ; PUTS  THE  OUTPUT  BUFFER  ADDRESS  IN  R4. 

MOV   ♦1BUF,RU    ;PUTS  INPUT  BUFFER  ADDRESS  IN  RO  (REQUIRED 

J  INPUT  ARGUMENT  FOR  SCDTB  ROUTINE). 
LOOP:    CALL  SCDTB       ; CALLS  CONVERSION  ROUTINE 

MOV   Ri,(R4)-t-    ;  PLACE  CONVERTED  NUMBER  IN  BNUM 

CMP   »11,K2      ;COMPARE  ASCII  TAB  (HT)  VALUE  TO  TERMINATING 

.-CHARACTER  RETURNED  IN  R2. 
BEQ   LOOP        ;IF  EQUAL,  STRING  SUCCESSFULLY  CONVERTED; 

;G0  BACK  THROUGH  LOOP  TO  CONVERT  NFXT  INPUT 

; STRING  POINTED  TO  BV  RO. 
CMP   »4U,R2      ;COMPARE  SPACE  VALUE  (40)  WITH  TERMINATING 

jCH^RACTER  IN  R2. 
BEQ   lUS  ;IF  EQUAL,  CONTINUE  i»ROGRAM  (ALL  INPUT 

;HAS  BEEN  CONVERTED  SUCCESSFULLY) . 
JMP   ERR  ;IF  NOT  EQUAL,       AL  CHARACTER  IN  INPUT 

;STRING  CAUSED  r     :RSION  TO  TERMINATE;  HENCE 

; INPUT  IS  ERRONEoow,  GO  TO  ERROR  ROUTINE. 
10$:     (continued  source  program) 


4.3   ASCII  TO  RADIX-50  CONVERSIONS 

There  are  two  system  library  routines  that  convert  ASCII   alphanumeric 
input  characters  to  16-bit  Radix-50  values: 

•  The  ASCII  to  Radix-50  Conversion  Routine  (SCATS),  which 
accepts  input  characters  from  the  ASCII  subset  and  converts 
them  to  Radix-50  format,  described  in  Section  4.3.1. 

•  The  ASCII  With  Blanks  to  Radix-50  Conversion  Routine  f$CAT5B), 
which  accepts  input  characters  fror.  the  ASCII  subset  and  blan!-. 
characters  and  converts  them  to  Radix-50  format,  described  in 
Section  4.3.2. 

The   Integer   Multiply   Routine   (SMUL)   is   called   to   perform    the 
multiplication  required  for  the  conversion. 


4.J.1   ASCII  to  Radix-50  Conversion  Routine  (SCATS) 

Tt.o  SCATS  routine  converts  from  one  to  three  ASCII  characters  to  a 
16-bit  Radix-50  value. 

Valid  characters  in  the  ASCII  string  to  be  converted  are: 

•  Alphabetic  characters  A  -  Z. 

•  Numeric  characters  0-9. 

•  The  characters:   dollar  sign  (S)  and  period  (.). 

For  complete  conversion  the  string  must  contain  three  valid 
characters.  Invalid  characters  will  cause  the  SCAT5  routine  to 
terminate  conversion.  When  an  invalid  character  is  found  in  the  input 
string,  the  converted  value  will  represent  the  valid  character  (s)  and 
trail ing  blank ( s) . 
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NOTE 


A  blank  character  (space)  in  the  ASCII 
character  string  will  cause  the  SCAT5 
routine  to  terminate.  If  blanks  are  to 
be  included  as  valid  characters  in  the 
string,  the  SCAT5B  routine  should  be 
called  to  perforin  the  conversion  (see 
Section  4.3.2). 

To  call  the  $CAT5  routine: 

•  Input  ,  in  Register  0,  tht  address  of  the  first  character  in 
the  ASCII  string  to  be  converted. 

•  Input,  in  Register  1,  the  period  disposition  flag,  as  follows: 

Rl  »  0  to  specify  that  the  period  is  a  conversion  terminator 
(terminating  character). 

Rl  «  1  to  specify  that  the  period  is  to   be   accepted   as   a 
valid  character  snd  used  m  the  conversion  to  Radix-SO. 

•  Include  the  statement 

CALL  SCATS 

in  the  source  program. 

The  $CAT5  routine  calls  tne  SSAVRG  routine  to  save  and  restore 
registers  3-5  of  the  calling  task.  Outputs  from  the  SCAT5  routine 
are : 

•  RU  =  the  address  of  the  next  character  m  the  input  string. 

•  Rl  =  the  converted  Radix-SO  value  (1-3  characters). 

•  R2  »  the  terminating  character.  (This  is  the  last  ch.aracter 
m  the  string  that  was  converted,  or  the  invalid  character 
that  caused  conversion  termination.) 

•  Condition  Code: 

C  bit  ■  set  if  fewer  than  three  characters  were  converted. 

C  bit  ■»  clear  if  conversion  was  complete. 

The  user  can  determine,  in  the  task,  whether  conversion  was  complete 
by  testing  the  C  bit  in  the  Condition  Code  or'  the  content  of  Register 
2.  Since  the  address  of  the  next  character  in  the  input  strinq  is 
returned  in  Register  0,  successive  input  string  conversion  may  be 
effected  by  resetting  Rl  and  setting  up  a  processing  loop  back  to  the 
CALL  $CAT5  statement. 
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4.3.2   ASCII  with  BlanKs  to  Radix-50  Conversion  Routine  (SCAT5B) 

The  $CAT5b  routine  converts  an  ASCII  three-charactec  strinq,  including 
blank  characters,  to  a  16-bit  Radix-5u  value. 

Valid  characters  in  the  ASCII  string  to  be  converted  are: 

•  Alphabetic  characters  A  -  Z. 

•  Numeric  characters  0-9. 

•  The  characters:   dollar  sign  (5),  period  (.).  and  blank 

( space) . 

For  complete  conversion,  tne  string  must  contain  three  valid 
characters.  Invalid  characters  will  cause  the  $CAr5B  routine  to 
terminate  conversion.  When  an  invalid  character  is  found  in  the  input 
string,  the  converted  value  will  represent  the  valid  character (a)  and 
tr ai 1 ing  blank ( s) . 

To  call  the  SCAT5U  routine: 

•  Input,  in  Register  j,  tne  address  ot  thi^  t  i  r  .«^  i  .f:  jr  .ic  t».'r  in 
the  ASCII  string  to  be  converted. 

•  Input,  m  Register  I,  the  period  disposition  flag,  as  follows: 

Rl  "  0  to  specify  that  the  period  is  a  conversion  terminator 
(terminating  character) 

Rl  =  1  to  specify  that  the  p^- .  lod  is  to  be  accepted  as  a 
valid  character  and  used  in  the  conversion  to  the 
Rad' x-5u  value . 

•  Include  the  statement 

CALL  SCAT5B 

.   I  the  source  program. 

The  SCATdB  routine  calls  the  SSAVRG  routine  to  save  and  restore 
registers  3  -  5  of  the  calling  task.  Outputs  from  the  SCAfiD  routine 
are : 

•  RO  ^  th?  address  of  the  next  character  in  the  input  butfor. 

•  Rl  =  the  converted  Radix-50  value. 

•  R2  =  the  terminating  character.  (This  is  the  last  character 
in  the  string  that  was  converted,  or  the  invalid  character 
which  caused  conversion  termination.) 

•  Condition  Code: 

C  bit  =  set  if  conversion  was  incomplete. 

C  bit  "    clear  if  conversion  was  complete. 

The  user  can  determine-,  in  the  task,  whether  conversion  was  complete 
by  testing  the  C  bit  in  the  Condition  Code  or  the  content  of  Register 
2.  Since  the  address  of  the  next  character  in  the  input  string  is 
returned  in  Register  0,  successive  input  string  conversion  may  be 
effected  by  resetting  Rl  and  setting  up  a  processing  loop  back  to  the 
CALL  SCAT5B  statement. 
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4.3.3   Example 

The  following  source  statements  define  a   subroutine   tha*:   calls   the 
$CAT5  routine  to  convert  ASCII  input  data  to  Radix-50  format. 


CNVRTR:  JSR  R2,$SAVVR 

MOV  #ASDAT,RO 

CLR  Rl 

CALL  SCAT5 

BCC  2$ 

JMP  INER 

2$:      MOV  R1,RAD? 
RETURN 


CALLS  $SAVVR  ROUTINE  TO  SAVE  RO  -  R2. 

PUTS  THE  ADDRESS  Of  THE  FIRST  ASCII 

CHARACTER  IN  RO. 

SETS  Rl  TO  ZERO  TO  SPECIFY  THAT  PERIOD 

IS  CONVERSION  TERMINATOR. 

CALLS  $CAT5  ROUTINE  TO  CONVERT  ASCII 

TO  kMDIX-50. 

BRANCH  TO  2$  IF  C  BIT  IS  CLEAR 

(CONVERSION  COMPLETE) . 

JUMPS  TO  INPUT  ERROR  ROUTINE  (INER)  IF 

C  BIT  IS  SET  (CONVERSION  INCOMPLETE) . 

STORES  CONVERTED  CHARACTER  IN  RAD5. 

RETURNS  TO  MAIN  PROGRAM,  VIA  SSAVVR, 

WHEN  CONVERSION  COMPLETE. 
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OUTPUT  DATA  CONVERSION  ROUTINES 


The  output  data  con'  arsion  routines  convert  internally  stored  numeric 
data  to  ASCII  characters.  There  are  four  groups  of  output  data 
convemon  routines: 

•  Binary  to  decimal  conversion  routines,  described  in  Section 
5.1,  to  convert  binary  data  to  one  of  the  following: 

•  a  2-digit  day  date,  in  the  range  01-Jl. 

•  a  5-dig:t  unsigned  decimal  magnitude  number. 

•  a  5-digit  signed  decimal  number 

•  a  decimal  number  up  to  9  digits  in  length. 

•  Binary  to  .^::tal  conversion  routines,  described  in  Section  5.2, 
to  convert  binary  numbers  to  one  of  the  following  octal 
number r : 

•  a  6-digit  unsigned  octal  magnitude  number. 

•  a  6-digit  signed  octal  number. 

•  a  3-digit  octal  number. 

•  A  general  purpose  binary  conversion  routine,  to  convert  binary 
data  to  ASCII  format.  This  routine  may  be  called  directly  by 
the  user  to  perform  conver.  ion  from  binary  to  AS<"II  according 
to  user-defined  parameters,  or  it  may  be  callec  indirectly  be 
calling  the  binary  to  decimal  or  octal  routines  which  pass 
predefined  parameters  to  this  routine,  as  described  in  Section 

r.3. 

•  A  Radix-50  to  ASCII  conversion  routine,  to  convert  a  Radix-50 
value  to  a  3-character  ASCII  string,  as  described  in  Section 
5.4. 

The  output  data  routines  described  in  this  chapter  are  called  by  the 
Edit  Message  Routine  ($EDMSG) ,  described  in  Chapter  6,  to  convert  data 
to  be  formacted  for  output  to  printers  or  display  devices. 


5.1   BINARY  TO  DECIMAL  CONVERSIONS 

There   are   four   system   library   routines   th.it   convert   internally 
formatted  binary  numbers  to  external  ASCII  decinal  format: 
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•  Binary  Date  Conversion  Routine  ($CBDAT) ,  which  converts  an 
internally  stored  binary  date  to  a  2-digit  decimal  number,  as 
described  ir.  Section  5.1.1. 

•  Convert  Binary  to  Decimal  Magnitude  Routine  ($CBDMG) ,  whicn 
converts  an  internally  stored  binary  number  to  a  5-digit 
unsigned  ASCII  decimal  magnitude  value,  as  described  in 
Section  5.1.2. 

•  Convert  Binary  to  Signed  Decimal  Routine  ($CBDSG) ,  which 
converts  an  internally  stored  binary  number  to  a  5-digit 
signed  ASCII  decimal  number,  as  described  in  Section  5.1.3. 

•  Convert  Double-precision  Binary  to  Decimal  Routine  ($CDDMG) , 
which  converts  a  double-precision,  unsigned  binary  number  to 
an  ASCII  decimal  number  of  9  digits  or  less,  as  described  in 
Section  5.1.4. 

These  routines  use  predefined  parameters  that  are  passed  to  the 
general  purpose  conversion  routine  ($CBTA),  which  performs  the  actual 
binary  to  ASCII  conversion. 


5.1.1   Binary  Date  Conversion  Routine  ($CBDAT) 

The  $CBDAT  routine  converts  an  internally  stored  binary  date  to  a 
2-digit  decimal  number. 

The  $CBDAT  routine  uses  the  following  predefined  conversion 
parameters : 

radix  =  10. 

field  width  =  2.   characters 

sign  flag  =  UNSIGNED 

leading  zeroes  flag  =  NOSUP  (no  suppression) 

To  call  the  $CBDAT  routine: 

•  Supply  three  input  arguments  in  the  task's  source  code: 

•  in  Register  0,  the  starting  address  of  the  output  area  in 
which  the  converted  two-byte  dace  is  to  be  stoied. 

•  in  Register  1,  the  binary  date  to  be  converted. 

•  in  Register  2,  the  zero  suppression  indicator,  where: 

R2  =  0  to  specify  suppression  of  leading  zeroes  in   the 
converted  date,  which  will  be  left- justified. 

R2  =  nonzero  to  specify  that  leading  zeroes  are  not   to 
be  suppressed. 

•  Include  the  statement 

CALL  $CBDAT 

in  thf>  source  program. 

The  predefined  conversion  parameters  are  automatically  pushed  to  the 
stack  on  entry  to  the  SCBDAT  routine.  If  the  user  specifies,  via  R2  ■ 
0,  that  leading  zeroes  are  to  be  suppressed,  the  NOSUP  parameter  is 
reset.  In  any  case,  the  SCBDAT  routine  passes  the  parameters  in 
Register  2  to  the  General  Purpose  ainary  to  ASCII  Conversion  Routine 
($CBTA),  which  performs  the  actual  conversion  of  the  bi.iary  number. 
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The  $CBTA  routine   calls   the   $SAVRG   routine   to   save   and   restore 
registers  3  -  5  of  the  calling  task.   Registers  1  and  2  are  destroyed. 

Outputs  from  the  $CBDAT  routine  are: 

•  The  converted  day  date  (in  the  range  01-31)  in   the   specified 
output  area. 

•  RO  =  the  next   available   address   in   the   output   area   (the 
pointer  to  the  location  following  the  last  digit  stored). 

The  $CBDAT  routine  does  not  return  error  conditions  to  the  caller. 


5.1.2  Convert  Binary  to  Decimal  Magnitude  Routine  (SCBDMG) 

The  $CBDMG  routine  converts  an  internally  stored  binary  number  to  a 
5-digit  unsigned  ASCII  decimal  magnitude  number. 

The  $CBDMG  routine  uses  the  following  predefined  conversion 
parameters : 

radix  =  10. 

field  width  =  5.   characters 

sign  flag  =  UNSIGNED 

leading  zeroes  flag  =  NOSUP  (no  suppression) 

To  call  the  SCBDMG  routine: 

•  Supply  three  input  arguments  in  the  task's  source  code: 

•  in  Register  0,  the  starting  address  of  the  output  area  in 
which  the  converted  5-digit  numoer  is  to  be  stored. 

•  in   Register   1,   the   unsigned   binary   number    to    be 
converted . 

•  in  Register  2,  the  zero  suppression  indicator,  where: 

R2  =  0  to  specify  suppression  of  leading  zeroes  in  the 
converted  number.  The  output  number  will  be 
lef t-]ust 1 f led . 

R2  =  nonzero  to  specify  that  leading  zeroes  are  not  to 
be  suppressed. 

•  Include  the  statement 

CALL  SCBDMG 

in  the  source  program. 

The  predefined  conversion  parameters  are  automatically  pushed  to  the 
stack  on  entry  to  the  SCBDMG  routine.  If  tne  user  specifies,  via  R2  « 
0,  that  leading  zeroes  are  to  be  suppressed,  the  NOSUP  parameter  Is 
reset.  '^n  any  case,  the  SCBDMG  routine  passes  the  parameters  in 
Register  i.  to  the  General  Purpose  Binary  to  ASCII  Conversion  Routine 
(SCBTA),  which  performs  the  actual  conversion  of  the  binary  number. 

The  SCBTA  routine  calls  the  SSAVRG  routine  to  save  and  restore 
registers  3  -  5  of  the  calling  task.   Registers  1  and  2  are  destroyed. 

Outputs  from  the  SCBDMG  routine  are: 
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•  The  converted  number,  a  maximum  of  five  digits  in   length,   In 
the  specified  output  area. 

•  RO  »  the  next   available   address   in   the   output   area   (the 
pointer  to  the  location  followinq  the  last  digit  stored). 

The  SCBDMG  routine  does  not  return  error  conditions  to  the  callei. 


5.1.J   Convert  Binary  to  Signed  Decimal  Routine  ($CBDSG) 

The  $CBDSG  routine  converts  an  internally  stored  binary  number  to  a 
5-digit  signed  rtSCII  decimal  number. 

The  SCBDSG  routine  uses  the  following  predefined  conversion 
parameters : 

radix  *  lu. 

field  width  -  5.   characters 

sign  flag  »  SIGNED 

leading  zeroes  flag  •  NOSUP  (no  suppression) 

To  call  the  SCBDSG  routine: 

•  Supply  three  input  argumer.ts  in  the  task's  source  code: 

•  in  Register  0,  the  starting  address  of  the  output  area  in 
which  the  converted  5-digit  number  is  to  be  stored. 

•  in  Register  1,  the  binary  number  to  be  converted. 

•  in  Register  2,  the  zero  suppression  indicator,  where: 

R2  ■  0  to  specify  suppression  of  leading  zeros  in  the 
converted  number.  The  output  number  will  be 
lef t-]ust i  f ied . 

R2  «  nonzero  to  specify  that  leading  zeroes  are  not  to 
be  suppressed. 

•  Include  the  statement 

CALL  SCBDSG 

in  the  source  program. 

The  predefined  conversion  paran.eters  are  automatically  pushed  to  the 
stack  on  entry  to  the  SCBDSG  routine.  If  the  user  specifies,  via  R2  » 
0,  that  leading  zeroes  are  to  be  suppressed,  the  NOSUP  parameter  is 
reset.  In  any  case,  the  SCBDSG  routine  passes  the  parameters  in 
Register  2  to  the  General  Purpose  Binary  '.  (.<  ASCII  Conversion  Routine 
(SCBTA),  which  performs  tr.e  actual  converoion  of  the  binary  number. 

The  SCBTA  routine  calls  the  SSAVRG  routine  to  save  and  restore 
registers  3  -  5  of  the  calling  task.   Registers  1  and  2  are  destroyed. 
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Outputs  from  the  SCBDSC  routine  are: 

•  The  converted  number,  a  maximum  of  five  digits  in   length,   in 
the  specified  output  area. 

•  RO  X  the  next   available   address   in   the   output   area   (the 
pointer  to  the  location  following  the  last  digit  stored). 

The  SCBDSG  routine  does  not  return  error  conditions  to  the  caller. 


5.1.4   Convert  Double-Precision  Binary  to  Decimal  Routine  (SCDDMG) 

The  SCDDMG  routine  converts  a  double-precision,  unsigned  binary  number 
to  an  ASCII  decimal  number  of  up  to  9  digits  less  than  or  equal  to 
65,536xlo4  .  If  the  numbvT  contains  more  than  9  digits,  the  routine 
inserts  a  string  of  five  ASCII  asterisk  symbols  in  the  output  area. 

To  call  the  SCDDMG  routine: 

•  Supply  three  Input  arguments  In  the  task's  source  code: 

•  in  Register  C,  the  starting  address  of  the  output  area. 

•  In  Register  1,  the  address  of   the   two-word   Input   area 
contal.iing  the  double-precision  number. 

•  in  Register  2,  the  zero  suppression  Indicator,  where: 

R2  =  0   to   specify   that   leading   zeroes   are   to   be 
suppressed.   The  number  will  be  1  eft- just  I f led . 

R2  '  nonzero,  to  specify  that  leading  zeroes  are  not  to 
be  suppressed . 

NOTE 

If  the  five  moat  significant  digits  are 
zeroes,  they  will  be  automatically 
suppressed,  regardless  of  the  suppression 
Indicator  setting. 

•  Include  the  statement 

CALL  SCDDMG 

in  ths  source  program. 

The  SCDDMG  routine  calls  the  SSA'/RG  routine  to  save  and  restore 
registers  3  -  5  of  the  calling  task.  Registers  1  and  2  are  destroyed. 
The  SDDIV  routine  Is  called  to  perform  the  double-precision  division, 
and  the  General  Purpose  Binary  to  ASCII  Conversion  Routine  (SCBTA)  is 
called  to  perform  the  ac^ual  ASCII  conversion. 
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Outputs    from    the    SCDDMG    routine    ar?: 

•      PO    =■    the    pointer    to    the    next    avdilable   address    In      the 
storage   area. 


output 


The  converted  ASCII  number,  stored  In  the  output  area,  or  a 
string  of  ASCII  asterisks  If  more  than  9  digits  or  a  number 
greater  than  65,536x10^  resulted  In  the  conversion  attempt. 
If  the  number  was  successfully  converted,  the  output  area  will 
contain  from  four  to  nine  digits. 


5.1.5   Examples 

Examples    of    the    use    of   output    conversion      routines      are      presented       In 
thi  s    sect  Ion  . 


EXAMPLE    1.      The    following    are    source    statements      that      illustrate      the 
steps    required    to    call    the    SCBDAT   routine. 


MOV  #ASDAT,i»0 

MOV  5DAT,R1 

CLR  R2 

CALL  SCBDAT 


PITS    TH£    ADDRESS    OF    OUTPUT    AREA    IN    RO. 
PUTS    THE    BINARY    DATE,     AT    BOAT,     IN    HI. 
CLEARS    R2    TO    ZERO   TO   SPECIFY   THAT    LEADING 
ZEROES    ARE    TO    BE    SUPPRESSED. 
CALLS    THE    SCBDAT    ROUTINE. 


(cont I nue) 

EXAMPLE  2.  The  following  are  source  statements  to  call  the  SCDDMG 
routine  to  convert  a  double-precision  number  to  an  ASCII 
decimal    number    and    check    the    result. 


MOV 
MOV 

MOV 


»ASDN,RO 
#DPWRD,R1 

I4.,R2 


CALL 

SCDDMG 

CMPB 

#•*, ASDN 

BNE 

lOS 

JMP 

ERR 

lOS:       (continue) 


PUTS    ADDRESS    OF    Ot.'TPUT    AREA    IN    Rfi. 
PUTS    STARTING    ADDRESS    OF    DOUBLE- 
PRECISION     INPUT    WORD    IN    Rl. 
PUTS    NONZERO    IN    R2     (SETS    THE    ZERO 
INDICATOR    FLAG    TO    1)    TO    SPECIFY 
THAT    LEADING    ZEROES    ARE    NOT    TO 
BE    SU?r"ESSED. 
CALLS    THE    SCDDMG    ROUTINE. 
COMPARES    AN    ASCII    ASTERISK    SYMBOL    WITH 
A    BYTE    OF    THE    CONVERTED   NUMBER. 
IF    NOT    EQUAL   CONVERSION   WAS    SUCCESSFUL 
AND    PROGRAM    CONTINUES, 

IF    EQUAL,    JUMP   TO    ERROR    ROUTINE    ERR     (MORE 
THAN    NINE    DIGITS    WERE   CONVERTED   AND   THE 
OUTPUT    DATA    IS     INVALID). 
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5.2   BINARY  TO  OCTAL  CONVERSION 

There  are  three  system  library  routines  that  convert  internally 
formatted  binary  numbers  to  external  ASCII  octal  format: 

•  Convert  Binary  to  Octal  Magnitude  Routine  {$CBOMG) ,  which 
converts  an  internally  stored  binary  number  to  a  6-digit 
unsigned  ASCII  octal  magnitude  number,  as  described  in  Section 
5.2.1. 

•  Convert  Binary  to  Signed  Octal  Roctine  ($CBOSG)  ,  which 
converts  an  internally  stored  binary  number  to  a  6-digit 
signed  ASCII  octal  number,  as  described  in  Section  5.2.2. 

•  Convert  Binary  Byte  to  Octal  Magnitude  Routine  ($CBTMG)  ,  which 
converts  an  internally  stored  binary  byte  to  a  3-digit  ASCII 
octal  number,  as  described  in  Section  5.2.3. 

These  routines  use  predefined  parameters  that  are  passed  to  the 
general  purpose  conversion  routine  (SCBTA) ,  which  performs  the  actual 
binary  to  ASCII  conversion. 


5.2.1  Convert  Binary  to  Octal  Magnitude  Routine  ($CBOMG) 

The  $CBOMG  routine  converts  an  internally  stored  binary  number   to  a 
G-digit  unsigned  ASCII  octal  magnitude  number. 

The   $CBOMG   routine   uses    the    following    predefined   conversion 
parameters: 

radix  =  8. 

field  width  =  6.  characters 

sign  flag  =  UNSIGNED 

leading  zeroes  flag  =  NOSUP  (no  suppression) 

To  call  the  $CBOMG  routine: 

•  Supply  three  input  arguments  in  the  task's  source  code: 

•  in  Register  0,  the  starting  address  of  the  output  area  in 
which  the  converted  6-digit  number  is  to  be  stored. 

•  in  Register  1,  the  binary  number  tr  be  ^.onverted. 

•  in  Register  2,  the  zero  suppressic n  indicator  where: 

R2  =  0  to  specify  suppression  of  leading  zeroes  in  the 
converted  number.  The  ou'-put  number  will  be 
left-justified. 

R2  =  nonzero  to  specify  that  leading  zeroes  are  not  to 
be  suppressed. 

•  Include  the  statement 

CALL  $CBOMG 
in  the  source  program. 
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The  predefined  conversion  parameters  are  automat  really  pushed  to  the 
stack  on  entry  to  the  $CBOMG  routine.  If  the  user  specifies,  via  R2  = 
0,  that  leading  zeroes  are  to  be  suppressed,  the  NOSUP  parameter  is 
reset.  In  any  case,  the  $CBOMG  routine  jasses  the  parameters  in 
Reqister  2  to  the  General  Purpose  Binary  to  ASCII  Conversion  Routine 
{$CBTA) ,  which  performs  the  actual  conversion  of  tne  binary  number. 

The  $CBTA  routine  calls  the  $3AVRG  routine  to  save  and  restore 
registers  3  -  5  of  the  calling  task.   Registers  1  and  2  are  destroyed. 

Outputs  from  the  $CBOMG  routine  are: 

•  The  converted  number,  a  maximum  of  six  digits   in   length,   in 
the  specified  output  area. 

•  RO  =  the  next   available   address   in   the  output   area   (the 
pointer  to  the  location  following  the  last  digit  stored). 

The  $CBOMG  routine  does  not  return  error  conditions  to  the  caller. 


5.2.2  Convert  Binary  to  Signed  Octal  Routine  ($CBOSG) 

The  $CBOSG  routine  converts  an  internally  stored  binary  numbrr  to  a 
b-digit  signed  ASCII  octal  number. 

The  $CBOSG  routine  ujes  the  following  predefined  conversion 
parameters : 

radix  =  a. 

field  width  =  6.   characters 

sign  flag  =  SIGNED 

leading  zeroes  flag  =  NOSUP  (no  suppression) 

To  call  the  $CBOSG  routine: 

•  Supply  three  input  arguments  in  the  task's  source  code: 

•  in  Register  0,  the  starting  address  of  the  output  area  in 
which  the  converted  6-digit  number  is  to  be  stored. 

•  in  Register  1,  the  binary  number  to  be  converted. 

•  in  Register  2,  the  zero  suppression  indicator,  where: 

R2  =  0  to  specify  suppression  of  leading  zeroes  ir  the 
converted  number.  The  output  number  will  be 
lef t- justi  f ied . 

R2  =  nonzero  to  specify  that  leading  zeroes  are  not  to 
te  suppressed. 

•  Include  tlie  statement 

CALL  $CBOSG 

in  the  source  program. 

The  predefined  conversion  parameters  are  automatically  pushed  to  the 
stack  on  entry  to  the  $CBOSG  routine.  If  '.he  user  specifies,  vi?  R2  « 
0,  that  leading  zeroes  are  to  be  suppressed,  the  NOSUP  parameter  is 
reset.  In  any  case,  the  $CBOSG  routine  passes  the  parameters  in 
Register  2  to  the  General  Purpose  Binary  to  ASCII  Conversion  Routine 
(SCBTA) ,  which  performs  the  actual  conversion  of  the  binary  number. 
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The  $CBTA  routine  calls   the   iiSAVRG   routine   to  save   and   restore 
registers  3  -  5  of  the  calling  task.   Regsiters  1  and  2  are  destroyed. 

Outputs  from  the  $CBOSG  routine  are: 

•  The  converted  number,  a  maximum  of  six  digits   m   length,   in 
the  specified  output  area. 

•  RO  =  the  next   available   address   in   the   output   area   (the 
pointer  to  the  location  following  the  last  digit  stored). 

The  $CBOSG  routine  doe?  r.ot  return  error  conditions  to  the  caller. 


5.2.3  Convert  Binary  Byte  to  Octal  Magnitude  Routine  (SCBTMG) 

The  SCBTMG  routine  converts  an  internally  stored  binary  byte  to  a 
3-digit  ASCII  octal  number. 

The  SCBTMG  routine  uses  the  following  predefined  conversion 
parameters : 

radix  =  8. 

field  width  =  3  characters 

sign  flag  =  UNSIGNED 

leading  zeroes  flag  =  NOSUP  (no  suppression) 

To  call  the  SCBTMG  routine: 

•  Supply  three  input  arguments  in  the  task's  source  code: 

•  if.  Register  0,  the  starting  address  of  the  output  area  in 
which  the  converted  3-digit  number  is  to  be  s"^  red. 

•  in  Register  1,  the  binary  byte  to  be  converted  in  the  low 
order  byte. 

•  in  Register  2,  the  zero  suppression  indicator,  where: 

R2  =  U  to  specitv  suppression  of  leading  zeroes  in  the 
converted  number.  The  output  number  will  be 
left- just i  f ied  . 

R2  =  nonzero  to  specify  that  leading  zeroes  are  not  to 
be  suppressed. 

•  Include  the  statement 

CALL  SCBTMG 

in  the  source  program. 

The  predefined  conversion  parameters  are  automatically  pushed  to  the 
stack  on  entry  to  the  SCBTMG  routine.  If  the  user  specifies,  via  R2  = 
0,  that  leading  zeroes  are  to  be  suppressed,  the  NOSUP  parameter  is 
reset.  In  any  case,  the  SCBTMG  routine  passes  the  parameters  in 
Register  2  to  the  General  Purpose  Binary  to  ASCII  Conversion  Routine 
(SCBTA) ,  which  performs  the  actual  conversion  of  the  binary  byte. 

The  SCBTA  routine  calls  the  SSAVRG  routine  to  save  and  restore 
registers  3  -  5  of  the  calling  task.   Registers  1  and  2  are  destroyed. 
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Outputs  from  the  $CBTMG  routine  are: 

•  The  converted  number,  a  maximum  of  three  digits  in  length,   in 
the  specified  output  area. 

•  RO  =  the  next   available   address   in   the   output   area   (the 
pointer  to  the  location  following  the  last  digit  stored). 

•  Rl  »  low  order  byte  is  unchanged;   high  order  byte  is   cleared 
by  the  $CBTMG  routine. 

The  SCBTMR  routine  does  not  return  error  conditions  to  the  caller. 


5.2.4   Example 

Following  are  source  statements  that  illustrate  the   calling   sequence 
of  the  binary  to  octal  conversion  routines. 


MOV  ♦OCOUT,R0 

MOV  BNUM,R1 

MOV  «7,R2 

CALL  §CBOMG 


PUTS  THE  STARTING  ADDRESS  OF  THE  OUTPUT 

AREA  IN  RO. 

PUTS  THf:  BINARY  NUMBER  TO  BE  CONVERTED 

IN  Rl. 

PUTS  THE  VALUE  7  IN  R2  (SETS  THE  ZERO 

INDICATOR  FLAG  TO  1)  TO  SPECIFY  THAT 

LEADING  ZEROES  ARE  NOT  TO  BE  SUPPRESSED. 

CALLS  THE  SCBOMG  ROUTINE. 


(continue) 


5.3   GENERAL  PURPOSE  BINARY  TO  ASCII  CONVERSION  ROUTINE  ($CBTA) 

The  $CBTA  routine  converts  internally  stored  binary  numbers  to  ASCII 
decimal  or  octal  numbers  when  called  by  the  binary  to  decimal  and 
binary  to  octal  conversion  routines  described  in  Sections  5.1  and  5.2 
of  this  chapter.  The  SCBTA  routine  converts  the  values  according  to 
predefined  parameters  which  the  calling  routine  passes  as  an  input 
argument  in  Register  2. 

The  $CBTA  routine  may  be  called  directly  by  the  user  to  convert 
internally  stored  binary  values  to  an  external  ASCII  format  according 
to  user-defined  conversion  parameters,  as  described  in  the  following 
paragraph . 

To  call  the  SCBTA  routine: 

•   Supply  three  input  arguments  in  the  task's  source  code; 

•  in  Register  0,  the  starting  address  of  the  output  area  in 
which  the  converted  ASCII  number  is  to  be  stored. 

•  in  Register  1,  the  binary  value  to  be  converted. 

•  in  Register  2,  the  conversion  parameters,  as  follows: 
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Bits    0-7:  (low   byte)    must    contain      the      conversion 

radix    (2.      to    16. ) • 

Bit    8:  must    contain    the    unsigned    flag    (    =    0)    if 

unsigned  value  to  be  converted;  or  must 
contain  the  sign  flag  (  =  1)  if  signed 
value    to    be    converted. 

NOTE:  The    minus    sign    is    not      counted 

in  a         field        width        when 

converting    a      negative      signed 
number. 

Bit    9:  zero   •upprcssion    flag    »    0;         or      nonzero 

suppression   flag   »    1. 

Bit    10:                         blank      fMl  flag        -         1         to        specify 

replacement  of        leading      zeroes      with 

blanks   only  if    nonzero    suppression      flag 

-    1. 

blank  fill  flag  =  0  to  spec?lfy  no 
replacement  of  leading  zeroes  if  bit  9  ■« 

1. 

Note:  When  the  zero  suppression 
flag  =  0,  the  blank  fill  flag 
is  ignored. 

Bits  11-15:       must  contain  a  numeric  value  from  1  -  32 
specifying  the  field  width. 

•   Include  the  statement 

CALL  SCBTA 

in  the  source  program. 

The  SCBTA  routine  calls  the  SSAVRG  routine  to  save  and  restore 
reglSwjrs  3  -  5  of  the  caller.  Registers  1  and  2  are  destroyed.  The 
Integer  Divide  Routine  ($DIV)  is  called  to  perform  the  required 
divis  ion . 

The  outputs  from  the  SCBTA  routine  are: 

•  The  converted  number,  from  1  to  32  digits  in   length,   in   the, 
specified  output  area. 

•  RO  =  the  next   available   address   in   the   output   area   (the 
pointer  to  the  location  following  the  last  digit  stored). 

The  SCBTA  routine  does  not  return  error  conditions  to  the  caller. 


5.4   RADIX-50  TO  ASCII  CONVERSION  ROimNE  (SCSTA) 

The  SCSTA  routine  converts  an  Internally  stored  16-bit  Radlx-50   value 
to  an  ASCII  character  string. 

To  call  the  SCSTA  routine: 

* 
•   Supply  two  input  arguments  in  the  task's  source  code: 
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•  In    Register    0,    the    address    at    which    the    first    byte    of    the 
converted    string    is    to    be    stored. 

♦  In      Register      1,      the      Radix-50      value      which      is      to      be 
converted  . 

•  Include    the    statement 

CALL    SCSTA 

in  the  source  program. 

The  $DIV  routine  is  called  to  perform  the  required  division. 

The  $C5TA  routine  does  not  use  registers  3-5.   Registers  1  and  2  are 
destroyed . 

The  outputs  from  the  $C5TA  routine  are: 

•  The  converted  ASCII  characters,  stored  In  a  maximum   of   three 
consecutive  bytes  in  the  specified  output  area. 

•  RO  *  the  address  of  the  next  byte   after   the   last   character 
stored  . 

The  $C5TA  routine  does  not  return  error  conditions  to  the  caller. 


5-12 


CHAPTER  6 
OUTPUT  FORMATTING  ROUTINES 


The  output  formatting  routines  convert  Internally  stored  data  to 
external  ASCII  characters  and  format  the  converted  characters  to 
produce  readable  output.   There  are  four  output  formatting  routines: 

•  The  Upper  Case  Text  Conversion  Routine  (SCVTUC),  which 
converts  lower  case  ASCII  text  to  upper  caje,  as  described  in 
Sect  ion  '5.1. 

•  The  Date  String  Conversion  Routine  (SDAT),  which  converts  a 
three-vord  binary  date  to  a  nine-character  ASCII  output 
string,  as  described  in  Section  6.2.1. 

•  The  Time  Conversion  Poutlnv  ($TIM),  whl-h  converts  r.he  binary 
time  to  an  ASCII  output  string,  as  described  in  Section  6.2.2. 

•  The  Edit  Message  Routine  fSEDMSG),  which  converts  internally 
stored  data  to  the  user-specified  type  of  ASCII  data 
(alphanumeric,  octal,  decimal)  and  formats  the  converted  data 
to  produce  meaningful  output  for  printing  or  display,  as 
described  In  Section  6.3. 


6.1   UPPER  CASE  TEXT  CONVERSION  ROUTINE  (SCVTUC) 

The  SCVTUC  routine  converts  lower  case  ASCII  text  to  upper  case.  The 
routine  performs  a  byte-by-byte  transfer  of  the  input  ASCII  character 
string,  converting  all  lower  case  alphabetic  characters  to  upper  rase, 
and  transferring  all  upper  case  characters. 

To  call  the  SCVTUC  routine: 

•  Supply  three  input  arguments  In  the  task's  source  code: 

•  in  Register  0,  the  address  of  the  text  string  to  be 
converted . 

•  in  Register  1,  the  address  of  the  output  area  for  the 
upper  case  string. 

•  In  Register  2,  the  number  of  bytes  in  the  string  to  be 
converted.  The  number  of  bytes  may  not  be  stated  as  0. 
A  statement  of  0  will  cause  SCVTUC  to  fail. 

•  Include  the  statement 
in  the  source  program. 
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The  SCVTUC  routine  does  not  use  reqis'-iers  3  -  5  of  the  calling  task. 
The  content  of  R2  (byte  count)  is  destroyed  on  output.  Regis>.ers  0 
and  1  are  left  pointing  past  the  input  and  output  areas,  respectively. 

The  SCVTUC  routine  converts  all  ASCII  alphabetic  characters  in  the 
input  string  to  upper  case.  Any  other  characters  are  mov^d  from  the 
input  area  to  the  output  area  in  their  sequential  positions.  The  user 
may  specify  the  input  area  address  as  the  output  area  address  (RO  = 
Rl)  when  the  SCVTUC  routine  is  called.  If  the  user  specifies  this  at 
the  outset,  RO  and  Rl  will  be  left  pointing  to  the  character  following 
the  string.  The  lower  case  alphabetic  characters  are  converted  to 
upper  case  in  place  in  the  input  area.  The  original  lower  case 
content  of  the  input  area  is  destroyed. 


6.2   DATE  AND  TIME  FORMAT  CONVERSION 

These  routines  convert  the  binary  date  and  time  to  formatted  ASCII 
output  strings.  The  date  is  converted  and  formatted  for  output  as 
f o 1  lows : 

day-month-year. 

The  time  is  converted  and  formatted  for  output  in  one  of  the  following 
forms : 

hour 

hour :mi  nute 

hour  :minute:second 

hour :minute:second :tick 

These  routines  and  the  procedures  for  using  them  are  described  in 
detail  in  the  following  sections. 


6.2.1   Date  String  Conversion  Routine  ($DAT) 

The  SUAT  routine  converts  the  three-word  internal  binary  date   to   the 
standard  eight-  or  nine-character  ASCII  output  format,  as  follows: 

dd-mmm-yy 

where : 

dd  =  day  (one  character  for  1  through  9  and 

two  characters  for  10  through  31) 
mmm  =  month  (first  3  letters) 
yy  =  year  (last  2  digits) 

To  call  the  SDAT  routine,  the  user  must: 

•   Supply  two  input  arguments  in  the  program's  source  code: 

•  in  Register  0,  the  address  of  the  output  area  in  which 
Lhe  converted  date  is  to  be  stored, 

•  in  Register  1,  the  address  of  the  three-word  input  area 
in  which  the  binary  date  is  stored.  The  input  area  must 
contain  the  following: 

word  1  =  last  two  digits  of  year 

word  2  =  a  number  from  1-12  (month  of  year) 

word  3  =  a  numeric  value  01  -  31  (day  of  month) 
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•  Include  the  statement 

CALL  $DAT 

in  the  source  program. 

NOTE:  The  $DAT  routine  does  not  perform  validity  checking  of  the 
input. 

The  $DAT  routine  calls  the  §SAVRG  routine  to  save  and  restore  the 
content  of  registers  3  -  5  of  the  calling  task.  The  $DAT  routine  uses 
Register  2  and  possibly  destroys  its  content.  Hence,  the  calling  task 
should  save  any  critical  value  in  Register  2  before  calling  the  $DAT 
routine.   Outputs  from  the  SDAT  routine  are  the  following: 

•  The  converted  date  string,   stored   in   the   specified  output 
area. 

•  RO  =  the  address  of  the  next  available  location  in  the  output 
area; 

•  Rl  =  the  next  address  (input  Rl  +  6)  in  the  input  area. 


6.2.2  Time  Conversion  Routine  ($TIM) 

The  $TIM  routine  converts  the  binary  time,  in  a  standard  format,  to  an 
ASCII  output  string  of  the  form: 

HH:KM;SS.S 

The  standard  format  for  STIM  input  values  is  shown   in   the   following 
table . 


Word 

Significance 

Output 
Format 

Value  Range 

WDl 

Hour-of-Day 

HH 

0-23 

WD  2 

Minute-of-Hour 

MM 

0-59 

WD  3 

Second-of -Minute 

SS 

0-59 

WD4 

Tick-of-Second 

.S 

depends  on  clock  frequency 

WD5 

Ticks-per -Second 

.S 

depends  on  clock  frequency 

To  call  the  STIM  routine: 

•   Supply  three  input  arguments  in  the  task's  source  code: 

•  in  Register  0,  the  address  of  the  output  area  in  which 
the  converted  time  is  to  be  stored. 

•  in  Register  1,  the  starting  address  of  the  input  area  in 

which  the  time  values  ate  stored. 

•  in  Register  2,  the  parameter  count,  where: 

R2  =  0  or  1,  to  specify  that  the  hour  (word  1)  is  to  be 
converted  in  the  format  HH. 
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R2  =  2,  to  specify  that  the  hour  and  minute  (words  1 
and  2)  are  to  be  converted  in  the  format  HH:MM. 

R2  =  3,  to  specify  that  the  hour,  minute,  and  second 
(words  1,  2,  and  3)  are  to  be  converted  in  the 
format  HH:MM:SS. 

R2  =  4  or  5,  to  specify  that  the  hour,  minute,  second, 
and  tick  are  to  be  converted  in  the  format 
HH:MM:SS,S  (where  .S  =  tenth  of  second). 


NOTE 

For  HH,  the  STIM  routine  returns  one 
character  for  values  between  1  and  9  and 
two  characters  for  values  greater  than 
9. 


•   Include  the  statement 
CALL  STIM 
in  the  source  program, 


NOTE 


The   STIM   routine   does    not    perform 
validity  check'ng  of  the  input  data. 

The  STIM  routine  calls  the  SSAVRG  routine  to  save  and  restore 
registers  3  -  5  of  the  calling  task.  The  contents  of  registers  0  and 
1  are  updated  and  returned  to  the  calling  task.  Register  2, 
containing  the  parameter  count,  is  destroyed. 

The  outputs  from  the  STIM  routine  are  the  following: 

•  The  converted  time  string,  which  is  storecJ   in   the   specified 
output  area. 

•  RO  =  the  address  of  the  next  available  location  in  the   output 
area. 

•  Rl  =  the  address  of  the  next  word  in  the  input  area. 
The  STIM  routine  calls  two  system  library  routines: 

•  The  SDIV  routine,  which   performs   the   division   required   to 
convert  binary  values  to  ASCII  words. 

•  The   SCBDAT   routine,   which   actually   performs    the    time 
conversion,  two  digits  at  a  time. 
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6.2.3   Example 

Assume  a  program  contains  the  following: 

The  input  area  containing  the  three-word  binary  date  and  the  five-word 
binary  time: 


BDBLK:  .WORD  77. 
.WORD  11. 
.WORD  01. 
.WORD  10, 
.WORD  15. 
.WORD  35. 
.WORD  XX 
.WORD  X 

The  output  area: 

DTBLK:    .BLKB   20, 


YEAR 

IITH  MONTH  (NOV) 

DAY 

HOUR 

MINUTES 

SECONDS 
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The  source  statements i 


EDIT  MESSAGE    $EDMSG 


MOV  IDTBLK.RO 

MOV  IBDBLK.Rl 

CALL  SDAT 

MOVa  111  ,  (R0)>- 


MOV    I3.,R2 
CALL   STIM 


PUTS  ADDRESS  OF  OUTPUT  ARKA  IN  RO. 

PUTS  ADDRESS  OF  INPUT  BINARY  DATE  AREA  IN  Rl 

CALLS  THE  SDAT  ROUTINE. 

PUTS  TAB  AFTER  DATE  IN  OUTPUT  BI'FFER. 

RO  NOW  CONTAINS  NEXT  ADDRESS  IN  DTBLK  FROM 

?DAT. 

Rl  NOW  CONTAINS  ADDRESS  OF  NEXT  WORD  (THE 

HOUR  10)  IN  BDBI.K  FROM  SLAT. 

SPECIFIES  THE  HH:MM:SS  FORMAT  FOR 

CONVERTED  TIME. 

CALLS  THE  STIM  ROUTINE. 


After  execution,  the  output  buffer  will  contain: 

l-NOV-77       in:15:3S 
The  time  and  date  fields  are  left- just i f led  . 

f=,.^      GENERALIZED  FORMATTING 

Generalized  output  formatting  is  provided  by  the  Edit  Messaije  Routine 
(SEDMSG) .  The  SEDMSG  routine  allows  the  user  to  request  the 
conversion  of  internally  stored  data  to  ASCII  decimal,  octal,  or 
alphanumeric  characters  and  to  control  the  layout  of  the  converted 
characters  to  produce  formatted  output  to  be  printed  or  displayed  as 
meaningful,  readable  text.  The  user  may  request  the  conversion  of 
strings  .)f  drita  and  their  formatting  in  columns.  Varying  ASCII  data 
types  can  be  incorporated  in  a  given  formatted  line  of  the  output. 
Spacing  within  lines  and  between  lines  can  be  controlled  by  the  user. 

The  procedures  for  converting  data  and  producing  formatted  output  with 
the  SEDMSG  routine  are  described  and  illustrated  in  the  following 
sect  ion . 


f;.3.1   Edit  Message  Routine  (SEDMSG) 


The  SEDMSG  routir.e  edits  internally  formatted  data,  in  an  argument 
block,  to  external  format  and  stores  it  in  the  calling  task's  output 
block.  The  editing  performed  by  thf.  SEDMSG  routine  is  specified  by 
user  directives  within  ,an  input  string.  Input  strings  may  contain 
ASCII  text  as  well  as  editing  directives.  Any  non-editing  directive 
characters  are  simply  copied  into  the  output  block.  Any  number  of 
directives  may  appear  in  an  input  string.  Input  strings  must  be  in 
ASCIZ  format.   Output  strings  are  in  ASCIZ  format. 
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Editing  directives  ace  of   two   types:    data   conversion   and   foiinat 
control.   The  directives  must  be  of  the  form: 

»1 ,  *nl  or  «V1 

where : 

?  is  a  delimiter  which  identifies  an  editir>j  ditei.-tive  to 
the  SEDMSG  routine. 

n  IS  an  optional  repeat  count  (decimal  number)  specifyimj 
the  number  of  times  the  editing  operation  is  to  be 
repeated  by  the  SEDMSG  routine.  If  n  -  0  or  is  not 
specified,  a  repeat  count  of  1  is  assumed. 

V  specifies  that  the  repeat  count  is  a  value  in  the  nexu 
word  in  the  task's  argument  block. 

1  is  an  alphabetic  letter  specifying  one  of  18  editing 
operations  to  be  performed  by  the-  SEDMSG  routinp,  is  ahowr. 
in  Table  6-1 . 

See  Section  6.3.2  for  examples   of   editing   directive   upe   in   input 
str  ings. 
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Table  6-1 
StDMSG  Routine  Editing  Directives 


Diractive 

Form 

Operation 

A 

(ASCII* 
String) 

tA 

Move   the  ASCII  character  from  address 
in  ARGBLK  to  OUTBLK. 

%nA 

Hove  the  next  n  ASCII  characters   froir 
address  in  ARGBLK  to  OUTBLK. 

%VA 

Use  the  value   In   the   next   word   in 
ARGBLK   as   reppat   count  and  move  the 
specified  number  of   ASCII   characters 
from  address  ir  ARGPI.K  to  OUTBLK. 

B 

(binary 
byte  to 
octal 
convers  ion) 

IB 

Convert    the   next   binary   bvte  from 
address   in   ARGBLK   to   o.-t^l   number 
and  store  result  in  OUTBLK. 

«nB 

Convert  the   next  n   binary  bytes  fror" 
address  in  ARGBLK   to   octal   numbers, 
and   store   results  in  OUTBLK;   Insert 
apace  between  numbers. 

%VB 

Use  the  value   in   the   next   word   in 
A'>G8LK   as   repeat   count,  convert  the 
specified  number  of  binary  bytes   from 
address   in   ARGBLK   to  octal  numbers, 
snd  <:tore  results  in   OUTBLK;    insert 
space  between  numbers. 

D 

(binaty  to 

signed 

decimal 

no 

suppression 

convers  ion) 

%0 

Convert  the  binary  value   in  the   next 
word  In   ARGBLK  to   siiined  dpcimal  and 
store  result  in  OUTBLK. 

%nD 

Convert  the   next   n   binary  values  in 
ARGBLK  to   signed   decimal   and   store 
result"  in  OUTBLK;   insert  tat-  between 
numbers . 

IVD 

Use  the  value   in   the   next   word   In 
ARGBLK   as   repeat   count,  convert  the 
specified  number  of  binary   values   to 
signed   decimal   and   store  results  in 
OUTBLK;   insert  taL  between  numbers. 

*   Extended  ASCI 
the   7-bit   ASC^ 
ASCII  input  stri 
while   the  A  dir 
output  block. 

KEY:   ARGBLK  =  T 
c 
c 

V 

I  charact'»r 
I   code, 
ng,  the  £  d 
ective  tran 

he  argument 
onverted, 
haracters  o 
alue. 

s  consist  of  the  printable  charactfr?   in 
If   non-printable  characteis  appe.ir  in  an 
irective   replaces   them  with   a   soacc, 
sters  the  non- pr intable  characters  to  the 

blcck  containing  the  binary  data   to   he 
the  addresses  of  ASCII  and  extended  ASCII 
r   the   address   of   a   double   preci.^lon 

IS  10  ^  t  0  C  0  o  ■  J  t.  p  u  I 


(continued  on  next  paqp) 
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Table  6-1  (Cont.) 
$EDMSG  Routine  Editing  Directives 


Directive 

Form 

Operation 

E 

(extended 

ASCII*) 

%E 

Move  the  extended  ASCII  character  from 
the  address  in  ARGBLK  to  the  OUTBLK. 

%nE 

Move  n  extended  ASCII  characters  from 
the  address  in  ARGBLK  to  OUTBLK. 

%VE 

Use  the  value  in  the  next  word  in 
ARGBLK  as  repeat  count  and  move  the 
specified  number  of  ASCII  characters 
from  the  address  in  ARGBLK  to  OUTBLK. 

F 

(form 

feed) 

%F 

Insert  a  form  feed  character  in 
OUTBLK. 

%nF 

Insert  n  form  feed  characters  in 
OUTBLK. 

%VF 

Use  the  value  in  the  next  word  in 
ARGBLK  as  repeat  count,  and  insert 
specified  number  of  form  feed 
characters  in  OUTBLK. 

I 

(include 
ASCIZ 
string) 

%I 

Use  the  next  value  in  ARGBLK  as  the 
address  of  an  ASCIZ  strinq  to  be 
logically  included  in  the  format 
string  at  this  point. 

M 

(binary  to 

decimal 

magnitude, 

0  suppress 

conversion) 

%M 

Convert  the  binary  value  in  the  next 
word  in  ARGBLK  to  decimal  magnitude 
with  leading  zeroes  suppressed  and 
store  the  result  in  OUTBLK. 

%nM 

Convert  the  next  n  binary  values  in 
ARGBLK  to  decimal  magnitude  with 
leading  zeroes  suppressed  and  store 
the  results  in  OUTBLK;  insert  tab 
between  numbers. 

%VM 

Use  the  value  in  the  next  word  in 
ARGBLK  as  repeat  count,  convert  the 
specified  number  of  binary  values  to 
decimal  magnitude  with  leading  zeroes 
suppressed  and  store  the  results  in 
OUTBLK;   insert  tab  between  numbers. 

*   Extended  ASCII  characters  consist  of  the  printable  characters   in 
the   7-bit   ASCII   code.    If   non-printable  characters  appear  in  an 
ASCII  input  string,  the  E  directive   replaces   them  with   a   space, 
while  the  A  directive  transfers  the  non-printable  characters  to  the 
output  block. 

KEY:   ARGBLK  =  The  argument  block  containing  the  binary  data   to   be 
converted,   the  addresses  of  ASCII  and  extended  ASCII 
characters  or   the  address   of   a  double  precision 
value. 

0UT3LK  =  The  output  block  in  which  $EDMSG  is  to  store  output. 

(continued  on  next  page) 
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Table  S-l  (Cont.) 
SEDMSG  Routine  Editing  Directives 


Di  rective 

Form 

Operat  ion 

N 

(new  line-- 
carriage  re- 
turn/1 ine 
feed) 

%N 

Insert    CR   and    LF   characters  in 
OUTBLK. 

%nN 

Insert   n   CR   and    LF  characters  in 
OUTBLK. 

%VN 

Use  the  value   in   the   next   word   In 
ARGBLK  as  repeat  count,  and  insert  the 
specified   number    of    CR   and    LF 
characters  in  OUTBLK. 

0 

(binary  to 

signed 

octal 

conversion) 

%0 

Convert   the  binary   value  in  the  next 
word   in   ARGBLK  to   signed  octal   and 
store  the  result  in  OUTBLK. 

%nO 

Convert   the  next   n   binary  values  in 
ARGBLK  to  signed  octal  and   store   the 
results  in  OUTBLK;   insert  tab  between 

numbers . 

%V0 

Use  the  value   in   the   next   word   in 
ARGBLK   as   repeat   count,  convert  the 
specified  number  of  binary   values   to 
signed  octal,  and  store  the  results  in 
OUTBLK;   insert  tab  between  numbers. 

P 

(binary  to 
octal  magni- 
tude, no  zero 
suppress 
conversion) 

%P 

Convert  the  binary  value  in  the   next 
word  in  ARGBLK  to  octal  magnitude  with 
no  leading  zeros   suppressed  and  store 
the  result  in  OUTBLK. 

%nP 

Convert  the   next   n   binary  values  in 
ARGBLK   to   octal   magnitude   with   no 
leading  zeros  suppressed  and  store  the 
results  in  OUTBLK;   insert  tab  between 
numDors. 

%VP 

Use  the  value   in   the   next   word   in 
ARGBLK   as   repeat   count,  convert  the 
specified  number  of  binary   values   to 
octal   magnitude  with  no  leading  zeros 
suppressed,  and  store  the   results   in 
OUTBLK;   insert  tab  between  numbers. 

KEY:   ARGBLK  =  The  argument  block  containing  the  binary  data   to   be 
converted,   the  addresses  of  ASCII  and  extended  ASCII 
characters  or   the   address   of   a   double   precision 
value . 

OUTBLK  =  The  output  block  in  which  $EDMSG  is  to  store  output. 

(continued  on  next  page) 
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Table  6-1  (Cont.) 
SEDMSG  Routine  Editing  Directives 


Directive 

Form 

Operat 1  on 

Q 

(binary  to 
octal  magni- 
tude, zero 
suppress 
conversion) 

%Q 

Convert  the  binary  value  in  the  next 
word  in  ARGBLK  to  octal  magnitude  with 
leading  .<eros  suppressed  and  store  the 
the  result  in  OUTBLK, 

InQ 

Convert  the  next  n  binary  values  in 
ARGBLK  to  octal  magnitude  with  leading 
zeros  suppressed  and  store  the  re'>ults 
in  OUTBLK;  insert  tab  between 
numbers. 

%vo 

Use  the  value  in  the  next  word  in 
ARGBLK  as  repeat  count,  convert  the 
specified  number  of  binary  values  to 
octal  magnitude  with  leading  zeros 
suppressed,  and  store  the  results  in 
OUTBLK;   Insert  tab  between  numbers. 

R 

(Radix-50 
to  ASCII) 

%R 

Convert  the  Radix-50  value  in  the  next 
word  in  ARGBLK  to  ASCII  and  store  the 
result  in  OUTBLK. 

%nR 

Convert  the  next  n  Radix-50  values  in 
ARGBLK  to  ASCII  and  store  the  results 
In  OUTBLK. 

%VR 

Use  the  value  in  the  next  word  in 
ARGBLK  as  repeat  count,  convert  the 
specified  number  of  Radlx-50  values  to 
ASCII,  and  store  the  results  In 
OUTBLK. 

S 
(space) 

%S 

Insert  a  space  In  OUTBLK. 

%nS 

Insert  n  spaces  in  OUTBLK. 

%VS 

Use  the  value  ir.  the  next  word  in 
ARGQLK  as  repeat  count,  and  insert  the 
specified  number  of  spaces  in  OUTBLK. 

T 

(double  pre- 

c  Ij'.i  on 

binary  to 

decimal 

conversion) 

%T 

Convert  the  double-precision  unsigned 
binary  value  at  the  address  in  ARGBLK 
to  decimal  and  store  result  In  OUTBLK. 

%nT 

Convert  the  next  n  double-precision 
binary  values  starting  at  the  address 
in  ARGBLK  to  decimal  and  store  results 
In    OUTBLK;     insert    tab   between 

numbers. 

%VT 

Use  the  value  in  the  next  word  in 
ARGBLK  as  repeat  count,  convert  the 
specified  number  of  double-precision 
binary  values  starting  at  the  address 
in  ARGBLK  to  decimal,  and  store  the 
results  in  OUTBLK;  insert  tab  between 
numbers. 
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KEY:  ARGBLK  =  The  argument  block  containing  the  binary  data  to  be 
converted,  the  addresses  of  ASCII  and  extended  ASCII 
characters  or  the  address  of  a  double  precision 
value. 

OUTBLK  =  The  output  block  in  which  $EDMSG  Is  to  store  output. 


(continued  on  next  page) 
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Table  6-1  (Cont. ) 
$EDMSG  Routine  Editing  Directives 


Direct  Ive 

Form 

Operation 

U 

(binary  to 
decimal  mag- 
nitude, no 
0  suppress 
conversion) 

»U 

Convert  the  binary  value   in  ARGBLK  to 
decimal    maqnitude   with   no   leading 
zeroes   suppressed  and  store  result  In 
OUTBLK. 

tnU 

Convert   the   next  n   binary  values  In 
ARGBLK  to  decimal   maqnitude   with   no 
leading   zeroes   suppressed   and  store 
results  in  OUTBLK;   Insert  tab  between 
numbers. 

%VU 

Use  the  value   in   the   next   word   In 
ARGBLK   as   repeat   count,  convert  the 
specified  number  of  binary   values   to 
decimal    magnitude   with   no   leadlnq 
zeroes  suppressed  and  .store  results  in 
OUTBLK;   insert  tab  between  numbers. 

X 

(file  name 
str  ing 
conversion) 

%X 

Convert   Radix-50  file  name  string   In 
ARGBLK    to   ASCII   string   in   format 
NAME.TYP;    convert    octal     version 
number,  if  present,  to  ASCII  and  store 
results  In  OUTBLK. 

%nX 

Convert   next   n   Radlx-50   file   name 
strings   in   ARGBLK  to  ASCII  string  In 
format    NAME.TYP;     convert     octal 
version   numbers,  If  present,  to  ASCII 
and  store  results  In   OUTBLK;    Insert 
tab  between  strings. 

IVX 

Use  the  value   In   the   next   word   in 
ARGBLK    as    repeat    count,   convert 
specified  number  of  Radix-50  file  name 
strlnqs   to   ASCII   strlnqs   In  format 
NAME.TYP;     convert    octal    version 
numbers,   if   present,   to   ASCII   and 
store  results  in  OUTBLK;    Insert   tab 
between  strings. 

Y 

(date  con- 
version) 

lY 

Convert   the   next  three  binary  words 
in  ARGPLK   to   ASCII   date   In   format 
dd-mmm-yy  and   store   In   OUTBLK.    In 
this  directive  a  repeat  Is  acceptable, 
but  will  be  ignored. 

KEY:   ARGBLK  -  The  argument  block  contain'ng  the  binary  data   to   be 
converted,   the  addresses  of  ASCII  and  extended  ASCII 
characters  or   the   address   of   a   double   precision 
value. 

OUTBLK  »  The  output  block  in  which  SEDMSG  is  to  store  output. 

(continued  on  next  page) 
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Table  6-1  (Cont.) 
$EDMSG  Routine  Editing  Directive? 


Directive 

Form 

Operat  ion 

Z 

(binary  time 

to  ASCII 

conversion) 

%oz 

or 

%1Z 

Convert  binary  hour-of-day  in  the  next 
word   of   AHGBLK  to  ASCII  and  store  in 
OUTBLK  in  format  HH. 

I2Z 

Convert   the   binary   hour-cf-day   and 
minute-of-hour   in   the  next  two  words 
of  ARGBLK  to  ASCII  and  store  in  OUTBLK 
in  format  HH:MM. 

%3Z 

Convert    the    binary    hour-of-day, 
minute-of-hour,   and   second-of -m inute 
in  the  next  three  words  of   ARGBLK   to 
ASCII   and   store   in  OUTBLK  in  format 
HH:MM:SS. 

t4Z 

or 

»5Z 

Convert   the  binary        hour-of-day, 
minute-of-hour,   second-of-ir  Inute,  and 
tioks-of -second  or  t Icks-per-second  in 
the  next  five  words  of  ARGBLK  to  ASCII 
and   store    in    OUTBLK    in    format 
HH:MM:SS.S,     where    .S  ■  tenth    of 
second. 

< 

(define 

byte 

field) 

ln< 

Insert  n   ASCII   spaces   followed  by  a 

field  mark   (NUL)  in  OUTBLK   to  define 
a  fixed  length  byte  field.   The  output 
pointer  will  point  to  the  first  space. 

> 

(locate 

field 

mark) 

»n> 

Increment   the   OUTBLK  pointer  until  a 
field  mark   (NUL)   is  located  or  the  n 
repeat  count  is  exceeded. 

KEY:   AHGBLK  »  The  argument  block  containing  the  binary  data   to   bo 
converted,   the  addresses  of  ASCII  and  extended  ASCII 
characters  or   the   addr*»3S   of   a   double   orecision 
value. 

0UT8LK  =  The  output  block  in  which  $EDMSG  is  to  store  output. 

Prior  to  calling   the   SEDMSG   routine,   the   user   must   set   up   the 
appropriate  argument  block,  as  follows: 

•  If  ASCII  or  extended  Af.CII  characters  are  to  be  moved  to  the 
output  block,  the  argument  block  must  contain  the  addresses  of 
the  ASCII  characters. 

•  If  binary  byte  to  octal  conversion  is  to  be  performed,  the 
argument  block  must  contain  the  addresses  of  the  binary  bytes. 

•  If  binary  values  are  to  be  converted,  the  argument  block  must 
contain  the  values. 
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•  It  tile   name   string   conversion   is   to   be   specified,   the 
argument  block  must  contain  the  following: 

Word  1  "  Radix-50  file  name 
Word  i  "  R3d.x-50  file  name 
Word  J  ■  Kadix-5U  file  name 
Word  4  -  Radix-SU  file  type 
Word  5  ■  Dinary  version  number 

•  If  the  binary  date  is  to  be  converted,  the  argument  blocK  must 
contain  the  following: 

Word  I  >  year  (last  2  digits) 
Word  2  -  number  (1  -  12)  of  month 
Word  3  -  day  of  month  (1  -  Jl) 

There  is  no  validity  checking  of  the  date  values.  If 
erroneous  date  values  are  specified,  output  results  will 
be  unpredictable. 

•  If  the  binary  time  is  to  be  converted,  the  argument  block  must 
contain  the  following: 

Word  I  »  hour-of-day  (0  -  23) 

Word  2  "  minutG-of-hour  (0  -  59) 

Word  3  -  second-of -minute  (0  -  59) 

Word  4  "■  tick-of -second  (depends  on  clock  frequency) 

Word  5  ■  t icks-per-second  (depends  on  clock  frequency) 

To  call  the  SEDMSG  routine: 

•  Supply  three  input  arguments  in  the  task's  source  code: 

•  in  Register  0,  the  startirig  address  of  the  output  block. 

•  m  Register  1,  the  address  of  th*"  input  string. 

•  in  Reg)Ster  2,   the   starting   address   of   the   argument 
block. 

•  Include  the  statement 

CALL  SEDMSG 

in  the  source  program. 

The  SEDMSG  routine  calls  the  SSAVRG  routine  to  save  and  restore 
registers  3-5  of  the  calling  task.  The  SEDMSG  routine  calls  the 
output  data  conversion  routines  described  in  Chapter  5  and  in  Section 
6.2  of  this  chapter  to  convert  Dinary  data  to  the  specified  external 
format.  See  the  detailed  descriptions  of  individual  conversion 
routines  for  specific  output  formats. 

The  SEDMSG  routine  scans  the  mpuc  string,  character-by-charactor .  If 
non-directive  or  ("unknown"  directive)  characters  are  found,  they  arf> 
transmitted  directly  to  the  task's  output  block.  When  a  %  delimiter 
'S  found,  the  SEDMSG  routine  interprets  the  character (a)  following  the 
delimiter.  If  a  data  conversion  directive  is  encountered,  the  SEDMSG 
routine  accesses  the  argument  block,  converts  the  specified  data,  and 
transmits  it  to  the  output  block  If  a  format  control  directive  is 
encountered,   the   routine   generates   the   specified   control (s)   and 


followed  by  a  valid  operator,  or  if  mul  iple  delimiters  are  found,  the 
SEDMSG  routine  transmits  the  first  and  any  subsequent  delimiters  not 
followed  by  a  valid  directive  character  to  the  output  block. 
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Outputs  from  the  $EDMSG  routine  are: 

•  The  converted/formatted  data  in  the  output  block. 

•  RO  =  the  address  of  the  next  available  byte  in  the  output 
block.  This  byte  ia  cleared  by  $EDMSG  to  provide  a 
null-terminated  (ASCIZ)  string. 

•  Rl  =  the  length  of  the  output  block  (the  number  of  bytes 
transferred  to  the  output  block)  .  This  count  does  not  include 
the  null-terminating  byte. 

•  R2  =  the  address  of  the  next  argument  in  the  argument  block. 

The  user  may  call   an  appropriate   output   routine   to  ojtput   the 
converted/formatted  data. 


6.3.2  Examples 

Examples  of  the  use  of  the  SEDMSG  routine  to  convert  and  format  output 
data  are  presented  in  this  section. 

EXAMPLE  1:   Assume  a  program  contains  the  following: 

An  input  string  (ISTRNG) 

ISTRNG:   .ASCIZ   /%F%1 2S***TEXT***% 3N%8S%VD%2N%1 2S***END****/ 

The  argument  block 

ARGBLK:  .WORD  3. 

.WORD  99. 

.WORD  -37. 

.WORD  137. 

The  output  block  (OUTBLK) 

OUTBLK:   .BLKB  lOn. 

The  source  statements 

START:       MOV    #OIJTBLK,R0 

MOV  #ISTRNG,R1 

MOV  »ARGBLK,R2 

CALL  SEDMSG 

The  following  output  will  be  produced. 

*  *  *TEXT*  *  * 

99      -37      137 

***ENU***** 
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The  editing  directivfjs,  shown  above,  and  their  effect  are: 

%F    -   insert  a  form  feed  in  OUTBLK  (start  a  new  page). 

I12S  -  insert  12  spaces  in  OUTBLK  and  move  the  ASCII  strinq  to 
OUTBLK  (indent  the  first  line  12  spaces  and  insert  the 
header  ♦**TEXT***) . 

%3N  -  insert  3  pairs  of  CR-LF  characters  in  OUTBLK  (generate  two 
blank  lines) . 

168   -   insert  8  spaces  in  OUTBLK  (indent  the  next  line  8  spaces). 

IVD  •-  use  the  first  value  (3)  in  ARGBLK  as  che  repeat  count  and 
convert  the  next  3  binary  values  in  ARGBLK  to  signed 
decimal;  store  each  value,  followed  by  a  tab,  in  OUTBLK 
(output  three  signed  decimal  numbers  in  columnar  format). 

%2N  -  insert  2  pairs  of  CR-LF  characters  in  OUTBLK  (generate  one 
blank  line) . 

%12S  -  insert  12  spaces  at  the  beginning  of  a  line  in  OUTBLK  and 
move  the  ASCII  string  to  OUTBLK  (indent  12  spaces  and 
insert  the  test  ***end****) . 

EXAMPLE  2:   Assume  a  program  contains  the  following: 

An  input  string  (INSTR) 

INETRz   .ASCI2   /%F5S***B.   MABRV  WORK  REPORT  FROM  %Y  TO  «Y  ***/ 

The  argument  block  (IBLK) 

IBLK:   .WORD  77.     ;YEAR 

.WORD  8.      ;8TH  MONTH  (AUG) 

.WORD  22,     ;DAY 

.WORD  77,     ;YEAR 

.WORD  9.      ;9TH  MONTH  (SEP) 

.WORD  16,     ;DAY 

The  output  block  (PRBLK) 

PRBLK:   .BLKB  100. 

The  source  statements 

BEGIN:   MOV  #PRBLK,RO 

MOV  #INSTR,R1 

MOV  #IBLK,R2 

CALL  $EDMSG 
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The  following  output  will  be  produced: 

***B.   MABRY  WORK  REPORT  FROM  22-AUG-77  TO  16-SEP-77*** 

The  editing  directives  in  the  example  and  their  effect  ares 

%F    -   insert  a  form  feed  in  PRBLK  (start  a  new  page). 

%5S  -  insert  5  spaces  in  PRBLK  and  move  ASCII  string  to  PRBLK 
(indent  the  line  5  spaces  and  output  the  header  ***B. 
MABRY  WORK  REPORT  FROM) . 

%Y  -  convert  the  next  three  words  in  IBLK  to  formatted  date  and 
store  in  PRBLK  followed  by  ASCII  text  (insert  22-AUG-77  TO 
in  header  1 ine) . 

%Y  -  convert  next  three  words  in  IBLK  to  formatted  date  and 
store  in  PRBLK  followed  by  ASCII  text  (insert  16-SEP-77*** 
in  header  line)  . 
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The  dynamic  memory  management  routines  allow  the  user  to  manually 
manage  the  space  in  a  task's  free  dynamic  memory.  The  free  dynamic 
memory  consists  of  all  memory  extending  from  the  assembled  code  of  the 
task  to  the  highest  virtual  address  owned  by  the  task,  excluding 
resident  libraries. 

Initially,  free  dynami'.-  memory  is  allocated  as  one  large  block,  from 
the  highest  available  memory  address  downward.  Subsequent  memory 
block  allocations  are  made  within  the  available  memory  blocks. 
Available  memory  blocks  are  maintained  as  a  linked  list  of  blocks  in 
ascending  order,  pointed  to  by  a  two-word  listhead.  Each  free  memory 
block  contains  a  two-word  control  field,  where: 

•  The  first  word  contains  the  address  of  the  next  available 
block,  or  zero  if  there  is  not  another  block. 

•  The  second  word  contains  the  size  of  the  current  block. 

Memory  allocation  is  either  on  a  first-fit  or  best-fit  basis. 
Allocation  is  always  made  from  the  top  of  the  selected  available 
dynamic  memory  block.  The  second  word  of  the  blocK  is  adjusted  to 
reflect  the  new  size  of  the  current  block  of  available  dynamic  memory. 
As  memory  blocks  are  allocated  completely,  they  are  removed  from  the 
free  memory  list. 

When  memory  blocks  are  deallocated  (released),  they  are  returned  to 
the  free  memory  list.  The  released  memory  blocks  are  relinked  to  the 
free  memory  list  in  ascending  address  order.  If  possible,  released 
memory  blocks  are  merged  with  adjacent  memory  blocks  to  form  a  single, 
large  block  of  free  dynamic  memory. 

There  are  three  routines  that  are  called  to  perform  dynamic  memory 
management  functions: 

•  Initialize  Dynamic  Memory  Routine  ;SINIDM) ,  v  uch  initializes 
the  task's  free  dynamic  memorv. 

•  Request  Core  Block  Routine  ($RQCB) ,  a  system  library  routine 
which  allocates  blocks  of  memory  in  the  free  dynamic  memory. 

•  Release  Core  Block  Routine  (SRLCB),  a  system  library  routine 
which  releases  (deallocates)  previously  all  ^-ated  memory 
blocks  in  the  executing  task's  free  dynamic  memory. 
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7.1   USAGE  CONSIDERATIONS 

To  use  the  dynamic  memory  management  routines,  the  user   must   provide 
the  following  in  the  sourc«?  program: 

•  A  two-word  free  memory  listhead: 

FREEHD:   .BLKW  2 

•  Tne  appropriate  call  argument(s)  and  statement  for  the  given 
routine,  as  described  in  Sections  7.2,  7.3,  and  7.4  of  this 
chapter . 

At  task  build  time,  the  user  must  specify  the  following 

LB:  [1,1  I VMLIB/LB: INIDMzEXTSK 

to  include  the  memory  management  modules  INIDM  and  EXTSK  in  the  task. 


7.2   INITIALIZE  DYNAMIC  MEMORY  ROUTINE  (SINIDM) 

The  $INIDM  routine  establishes  the  initial  state  of  the  free  dynamic 
memory  available  to  the  executing  task.  The  free  dynamic  memory 
consists  of  all  memory  extending  from  the  end  of  the  task  code  to  the 
highest  virtual  address  used  by  the  task,  excluding  resident 
1 ibrar les . 

To  call  the  $INIDM  routine: 

•  Specify,  in   Register   0,   the   address   of   the   free   memory 
1 isthead  . 

•  Include  the  statement 

CALL  SINIDM 
in  the  source  program. 
The  outputs  from  the  SINIDM  routine  are: 

•  RO  »  the  first  address  in  the  task. 

•  Rl  «=  the  address  following  the  task  image  (the  last   available 

address  in  the  free  dynamic  memory). 

•  R2  =  the  size  of  the  free  dynamic  memory. 

For  the  RSX-ilM  system,  the  SINIDM  routine  deallocates  any  previous 
task  memory  extension  made  by  issuing  the  EXTKS  executive  directive  or 
by  calling  the  SEXTSK  routine  (see  Chapter  8). 

The  SINIDM  routine  performs  the  following: 

•  Rounds  the  free   dynamic   memory   base   address   to   the   next 
four-byte  boundary. 

•  Initializes  the  free  dynamic  memory  as  a  single  large  block  of 
memory. 
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•  Computes  th»»  total  size  of  the  free  dynamic  memory. 

•  Sets  the  outputs  in  Register  0  -  1  and  returns  to  the   calling 
task , 

Registers  3  -  S  are  not  used. 

After  the  dynamic  memory  has  been  initialized,  the  user's  task  may 
call  thv?  system  library  routines:  Request  Core  Block  Routine  (SRQCB) 
to  a' locate  memory  blocks  in  the  dynamic  memory;  and  subsequently 
call  the  Release  Core  Block  Routine  ($RLCB)  to  release  the  allocated 
blocks. 


7.3   REQUEST  CORE  BLOCK  ROUTINE  ($RQCB) 

The  §RQCB  system  library  routine  determines  whether  there  is  enough 
space  available  m  the  free  dynamic  memory  to  satisfy  an  executing 
task's  memory  allocation  request.  If  memory  is  available,  the  SRQCB 
routine  allocates  the  requested  memory  blo<ik. 

To  use  the  $RQCB  routine  the  user  must  initialize  dynamic  momory  once 
(usually  with  the  SINIDM  routine)  then: 

•  Supply  two  input  arguments  m  the  task's  source  code: 

•  in  Register  0,  the  address  of  the  free  memory  listhead. 

•  in  Register  1,  the  size  {number  of  bytes)  of   the  memory 
block  to  be  allocated,  where: 

Rl  «  a  value  jzeatei  than  or  equal  to  0,  to  specify 
best  fit  allocation. 

Rl  »  a  value  less  tnan  '  0,  to  specify  first  fit 
allocation.  (The  value  is  negated  to  determine 
block  size.) 

•  Include  the  statement 

CALL  SRQCB 

In  the  source  program. 

The  SRQCB  routine  calls  the  SSAVRG  routine  to  save  and  restore 
registers  3  -  5  of  the  calling  task.   Register  2  is  destroyed. 

The  SRQCB  routine  returns  the  following  output  to  the  calling  task: 

•  Successful  allocation: 

•  RO  «  dynamic  memory  address  of  the  allocated  block. 

•  Rl  =  the  actual  size  of  the   allocated   block   (requested 
size  rounded  to  next  two-word  boundary. 

•  Conditio!  Code  C  bit  «  clear. 

•  Unsuccessful  allocation: 

•  Condition  Code  C  bit  •  set. 
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7.4   RELEASE  COkti  BLOCK  ROUTINE  ($RLCB) 

Th"  SRLCB  system  library  routine  releases  a  block  of  previously 
allocated  dynamic  memory  to  the  free  memory  list,  which  is 
sequentially  ordered  by  the  memory  addrease*)  of  the  blocks  themselves. 

To  call  the  SRLCB  routine: 

•  Supply  three  input  arguments: 

e   In  Register  0,  the  address  of  the  free  memory  listheai. 

•   in  Register  1,  the  size  (number  of  bytes)  of  the  block  to 
be  released. 

e   in  Register  2,  the  memory  address  of   the   block   to  be 
released . 

•  Include  the  statement 

CALL  SRLCB 

in  the  source  program. 

The  SRLCB  routine  calls  the  SSAVRG  system  routine  to  save  and 
subsequently  restore  Registers  3  -  5  of  tne  calling  task.  Register  0 
is  unchanged.   Registers  1  and  2  are  destroyed. 

The  output  from  the  SRLCB  routine  is  the  released  block.  The  SRLCB 
routine  searches  the  free  meirory  list  until  the  proper  address  slot  is 
fc  and,  then  tne  released  bio  k  is  nerged  into  the  list.  If  possible, 
the  memory  block  to  be  released  is  merged  with  adjacent  blocks  already 
in  the  free  memory  list. 
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The  virtual  memory  management  routines  perform  memory  allocation  and 
deallocation  by  paging  to  and  from  disk  file  storage  to  accOirmodate 
tasks  that  require  more  memory  than  that  available  in  the  task's  free 
dynamic  memory  at  any  given  time.  That  is,  the  routines  allow  ^-e 
user  to  bring  pages  into  memory  when  they  are  needed,  hold  them  the  "■ 
until  they  arr  no  longer  needed,  swap  the  pages  out,  and  reallocatt 
their  memory  space  to  other  pages.  These  routines  do  not  require  the 
memory  management  hardware,  and  are  not  related  to  memory  management 
directives. 

The  virtual  memory  management  routines  perform  the  following  major 
functions: 

•  Virtual  memory  initialization. 

•  Dynamic  memory  allocation. 

•  Virtual  memory  allocation. 

•  Page  management. 

Although  the  user  may  call  the  individual  virtual  memory  management 
routines,  greater  efficiency  is  gained  by  using  them  as  an  automatic 
control  system  by  calling  only  key  routines,  as  follows: 

•  The  Initialize  Virtual  Memory  Routine  ($INIVM) ,  which 
initializes  the  task's  dynamic  memory  and  the  disk  work  file, 
as  described  in  Section  8.2. 

•  The  virtual  memory  allocation  routines:  Allocate  Virtual 
Memory  Routine  ($ALVRT)  and  Allocate  Small  Virtual  Block 
Routine  ($ALSVB)  ,  which  manage  the  allocation  of  large  and 
small  page  blocks  to  enable  page  swapping  to  and  from  dynamic 
memory,  as  described  in  Section  8.4. 

e  Four  page  management  routines: 

•  The  Convert  and  Lock  Page  Routine  ($CVLOK) ,  which 
coi. verts  a  virtual  address  to  a  dynamic  memory  address 
and  sets  a  lock  byte  in  the  memory  page  to  prevent  its 
being  swapped  out  of  memory  until  it  is  no  longer  needed. 
(See  Section  8.5.1.) 

•  The  Unlock  Page  Routine  ($UNLPG) ,  which  clears  the  lock 
byte  in  a  memory-resident  page  so  that  it  can  be  released 
and  its  memory  space  reallocated  to  another  page.  (See 
Section  8.5.7.) 
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•  The  Convert  Virtual  to  Real  Address  Routine  ($CVRL) , 
which  converts  a  virtual  address  to  a  dynamic  meiiiory 
address.   (See  Section  3.5.2). 

•  The  Wr ite-ir.arked  Page  Routine  {$WRMPG)  ,  which  sets  the 
"written  into"  flag  of  memory  pages.  (See  Section 
8.5.5)  . 


8.1   GENERAL  USAGE  CONSIDERATIONS 

To  call  the  virtual  memory  management  routines,  the  user  must  provide 
the  appropriate  call  arguments  and  statements  in  the  source  program, 
as  described  in  Sections  8.2  through  8.5  of  this  chapter. 

The  user's  task  must  contain  an  error  handling  routine,  as  described 
in  Section  8.1.1. 

At  task  build  time,  the  user  must  specify  the  file  and  the  virtual 
memory  management  modules  required  by  the  task,  as  described  in 
Section  8.1.2. 


8.1.1  User  Error  B&ndlin,  Requirements 

There  are  four  virtual  memory  management  routines  that  detect  fatal 
error  conditions  for  which  a  user-written  error  handling  routine, 
entitled  SERMSG,  is  required.   The  routines  are: 

•  Allocate  Block  Routine  ($ALRLK)  which  is  called  by  several 
other  virtual  memory  management  routines. 

•  Allocate  Virtual  Memory  Routine  ($ALVRT)  which  is  called  by 
the  user  or  by  the  Allocate  Small  Virtual  Block  Routine 
($ALSVB) . 

•  Read  Page  Routine  ($RDPAG)  which  is  called  by  the  Convert 
Virtual  to  Real  Address  Routine  ($CVRL) . 

•  Write  Page  Routine  ($WRPAG)  which  is  called  by  the  Get  Core 
Routine  (?GTCOR) . 

In  conjunction  with  the  SERMSG  routine,  the  user  must  include 
definitions  of  three  global  error  codes  and  one  global  severity  code 
in  the  task.   The  symbolic  error  codes  are: 

E$R4  (used  by  the  SALBLK  routine  when  there  is  no  dynamic 
memory  available  for  allocation.) 

E$R73  (used  by  the  $RDPAG  and  $WRPAG  routines  when  a  work 
file  I/O  error  occurs  during  an  attempt  to  swap  pages 
between  resident  memory  and  disk  storage.) 

E$R76  (used  by  the  $ALVRT  routine  when  there  is  no  virtual 
storage  available  for  allocation.) 

The  severity  code  is: 

SSV2  {used  by  the  four  routines  cited  above  to  denote  a 
fatal  error  that  must  be  corrected  before  task 
execution  can  resume.) 
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When  a  fatal  error  occurs,  the  detecting  routine  seta  up  two  input 
arguments: 

Register  1  »  low  byte:   error  code 

high  byte:   severity  code  (always  SSV2) 

Register  2  »  argument  block  address 

and  issues  the  call 

CALL  $ERMSG 

If  the  user  has  not  defined  the  error  handling  routine  within  the 
task,  the  undefined  global  symbol  diagnostic  message  will  be  output  at 
^ask  build  time. 

A  typical  error  handling  routine  would  output  a  message  to  indicate 
the  specific  error  condition,  close  all  files  (including  the  work 
file) ,  and  exit. 

The  user's  error  handling  routine  should  not  attempt  to  return  to  the 
virtual  memory  management  routine  that  detected  the  fatal  error,  since 
no  meaningful  output  would  result. 


8.1.2  Task  Building  Requir«vmenta 

There  are  two  versions  of  the  virtual  memory  management  routines:  the 
statistical  version  and  the  non-statistical  version.  Each  version 
consists  of  twelve  program  modules,  containing  one  or  more  routines, 
and  a  data  storage  module.  Individual  routines  in  the  virtual  memory 
management  routines  library  may  reference  other  routines.  The 
relationship  of  the  modules  and  routines  in  the  library  is  shown  in 
Table  8-1. 
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Table  8-1 
Content  of  the  Virtual  Memory  Management  Library  File 


Module  Name 

Name  of 
Routine(s) 

Routines  Referenced 

Statistical  Non-statistical 

ALBLK 

ALBLK 

$ALBLK 

SGTCOR,  SEXTSK,  SWRPAG 

ALSVB 

'  ALSVB 

SALSVB 

SALVRT,  SWRMPG,  SCVRL, 
SALBLK,  SRQVCB,  SFNDPG, 
SRDPAG 

CVRS 

CVRL 

SCVRL 

SFNDPG,  SALBLK,  SRDPAG 

EXTSK 

EXTSK 

$EXTSK 

(none) 

FNDPG 

FNDPG 

SFNDPG 

(none) 

GTC05 

GTCOR 

SGTCOR 

SEXTSK,*   SWRPAG 

INIDM** 

I  N I  DM  *  • 

$  I N  I  DM 

SEXTSK 

INIVS 

INIVM 

$INIVM 

SALBLK,  SGTCOR,  SEXTSK, 
SWRPAG 

MRKPG 

MRKPG 

SLCKPG 
SUNLPG 
SWRMPG 

SFNDPG 
SFNDPG 
SFNDPG 

RDPAS 

RDPAG 

SRDPAG 
SWRFAG 

(none) 

RQVCB 

RQVCB 

SRQVCB 

( none) 

VMUTL 

VMUTL 

SCVLOK 

SCVRL,  SLCKPG,  SFNDPG, 
SALBLK,  SRDPAG 

VMDAS 

VMDAT 

Global  data  storage  module 

*  The  Extend  Task  Routine  (SEXTSK)  is  called  by  the  SGTCOR  routine, 
but  only  if  WSSKST  has  been  defined  and  initialized  in  your  source 
program  at  task  build  time.   (See  Section  8.3.2.1  and  Figure  8-3B.) 

**  The  INIDM  module  is  a  dynamic  memory  management  module  (see  Chapter 
7)  that  normally  is  used  in  conjunction  with  the  virtual  memory 
management  routines. 
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Four  modules  in  the  statistical  version  of  the  routines  set  up  and/or 
maintain  statistics  of  the  usage  of  the  work  file  and  memory.  These 
modules  and  their  associated  statistical  data  fields  are: 

•  The  ISIIVS  modules,  which  initializes  three  double-word  fields: 
the  total  work  file  access  field  (SWRKAC);  the  work  file  read 
count  field  ($WRKRD);  and  the  work  file  write  count  field 
(SWKKWR)  .  Each  of  these  fields  is  a  double  word  integer 
contained  m  the  qlobal  data  storage  module  (VMDAS)  for  the 
statistical  version  of  the  routiner.. 

•  The  CVRS  module,  which  maintains  the  count  of  tofil  work  file 
accesses  in  the  SWRKAC  field. 

•  The  RDPAS  module,  which  maintains  a  total  of  the  work  file 
reads  in  the  SWRKRO  field  and  a  total  of  the  work  file  writes 
in  the  $WRKWR  field, 

•  The  GTCOS  module,  which  maintains  a  count  of  the  totnl  amount 
of  free  dynamic  memory  in  the  $KRSI7  sinqle-word  field.  This 
field  must  be  defined  and  in  1 1  la  I  i  zeu,  in  the  ."ource  program. 

The  statistical  version  of  the  virtual  memory  management  routines  does 
not  automatically  report  these  statistics.  It  is  the  user's 
responsibility  to  provide  for  the  output  of  the  statistical  data  in 
the  fields  described  aoove  if  the  statistical  version  of  the  routines 
1 s  used . 

To  use  the  statistical  routines,  the  user  must  specify,  at  task  build 
time,  the  virtual  T^emory  management  routines  library  file,  the  names 
of  all  statistical  moaules  whose  routines  will  be  used  at  tar>k 
execution  time,  and  the  name  of  the  global  data  storage  module.  The 
only  optional  modules  are  ALSVB  and  INIOM.  Following  is  a 
specification  that  identifit-  all  modules  of  the  statistical  version 
of  the  routines. 

LB: 11, 1 1 VMLI B/LB :ALBLK: ALSVB :ALVRT: CVRS :EXTSK:FNDPG: GTCOS 

LB:  i  1  ,  1)  VMM  B/LB:  I  N  I  VS  :  >1RKPG  :  RDPAS  :  RQVCB  :  VMUTL  :  INIDM:VMDA> 

The  non-stat I  St ica I  routines  use  the  global  data  storage  module, 
VMDAT.  To  use  the  non-statistical  routines,  the  user  must  specify,  at 
task  build  time,  the  virtual  memory  management  routines  library  file, 
the  names  of  all  non-statistical  modules  whoso  routines  will  be  used 
at  task  execution  time,  and  the  name  of  the  global  data  storage 
module.  The  only  optional  modules  are  ALSVB  and  INinM.  Following  is 
a  specification  that  identifies  all  modules  of  the  non-statistical 
version  of  the  routines. 

LB:  11,1 1 VMLT B/LB: ALB LK: ALSVB: A LVRT:CVRL:EXTSK :FNDPG!GTCOR 

LB:  1  1,  1]  VMLIB/f.B:  IN  I  VM  :  «1RKPG  :  RDPAG  :  HQVCB  :  VMUTL:  INIDM:VMDAT 


8.2   VIRTUAL  MEMORY  INITIALIZATION  ROUTINE  (SINIVM) 

The  SINIVM  routine  initializes  the  task's  free  dynamic  memory,  sets  up 
the  page  address  control  list,  and  initializes  the  user's  disk  work 
file  to  enable  memory-to-disk  page  swapping.  Disk  work  file  capacity 
is  64K  words. 
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To  use  the  $INIVM  routine: 

•  Define  and  initialize  a  two-word  field  named  SFRHD.   To  define 
the  field,  include  the  code 

SFRHD: :  .BLKW  2. 

in  the  source  program.   To  initialize   the   field,   store   the 
starting  address  of  the  free  dynamic  memory  in  SFRHD. 

•  Define  three  global  symbols  in  the  source  program: 

WSKLUN  Logical  unit  number  (LUN)  to  be  used  for  the  work 
file.  The  user  is  also  responsible  for  assigning 
this  LUN  to  a  disK  device. 

WSKEXT  Work  file  extension  size  (in  blocks).  A  negative 
number  indicates  that  the  extend  should  first  be 
requested  as  a  contiguous  allocation  of  disk  blocks. 
A  positive  number  indicates  that  the  extend  need  not 
be  contiguous. 

'ast  page  search  page  count.  If  there  is  sufficient 

dynamic   memory   to   allocate  at  least  the  number  of 

pages  specified,  512  words  of  dynamic  memory  will  be 

set    aside    to    speed    up  the    searching    of 
memory-resident  pages. 

•  Specify,  in  Register  1,  the  highest  address  of  the  task's  free 
dyna.Tiic  memory. 

•  Include  the  statement 

CALL  SINIVM 

in  tJ.e  source  program. 

NOTE:  Before  calling  the  SINIVM  routine,  the  task  may  call  the  SINIDM 
routine  (see  Chapter  7),  which  returns  the  last  address  of  dynamic 
memory  and  the  total  size  of  dynamic  memory. 

The  outputs  from  the  SINIVM  routine  are: 

•  Initialization  successful: 

Condition  Code  C  bit  =  clear. 

and 

RO  =  0. 

•  Initialization  failure: 

Condition  Code  C  bit  »  set. 

and 

RO  =  -2  to  indicate  work  file  open  failure. 

RO  =  -1  to  indicate  work  file  mar k- f or -delet  ion  failure. 

Also,  the  FCS  error  code  may  be  examined  at  offset  F.ERR 
in  the  work  file  FOB.  The  address  of  the  FDB  is  stored 
in  the  word  SWRKPT. 
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The  interaction  of  the  SINIVM  routine  with  the  user's  task  and  the 
Allocate  Block  Routine  (SALBLK)  is  shown  in  Figure  8-1  and  described 
below. 
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Figure  8-1   General  Block  Diagram  of  the  SINIVM  Routine 
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The  $INIVM  routine  calls  the  $SAVRG  routine  to  save  and  subsequently 
restore  registers  3  -  5  of  the  calliny  task. 

Starting  at  the  high  address  of  the  calling  task's  free  dynamic 
memory,  the  $INIVM  routine  clears  control  fields  and  the  page-  address 
control  listhead.  The  ?INIVM  routine  then  sets  up  the  heading  for  a 
new  page  address  control  list  and  calls  the  Allocate  Block  Routine 
($ALBLK)  to  allocate  a  memory  page  block  for  the  control  list.  The 
$INIVM  routine  then  calls  the  SALBLK  routine  to  allocate  a  page  block 
for  the  first  memory  page  for  the  calling  task.  The  $INIVM  routine 
links  the  first  allocated  page  to  the  page  control  list. 

The  $INIVM  routine  initializes  (opens)  the  user's  disk  work  file.  If 
the  file  is  opened  successfully,  the  $INIVM  routine  attempts  to  mark 
it  for  deletion.  This  ensures  that  the  file  will  be  deleted 
automatically  when  it  is  closed,  or  if  the  task  terminates  abnormally 
or  exits.  Note  that  the  work  file  may  be  closed  by  the  following 
operation:  CLOSE?  SWRKPT.  If  the  routine  is  successful,  the  C  bit  in 
the  Condition  Code  is  cleared,  and  control  is  transferred  to  the 
$SAVRG  routine  to  restore  registers  R3  -  R5  and  return  to  the  calling 
task. 

If  the  work  file  is  not  opened  successfully,  the  SINIVM  routine  sets 
the  C  bit  in  the  Condition  Code,  sets  RO  =  -2,  and  transfers  to  the 
$SAVRG  routine. 

If  the  work  file  is  not  successfully  marked  for  deletion,  the  SINIVM 
routine  sets  the  C  bit  in  the  Condition  Code,  sets  RO  =  -1,  and 
transfers  to  the  $SAVRG  routine. 

The  $SAVRG  routine  restores  registers  R3  -  R5  and  returns  to  the 
calling  task.   The  original  content  of  RO  -  R2  is  destroyed. 


8 . 3   CORE  ALLOCATION  ROUTINES 

The  core  allocation  routines  manage  the  allocation  and  deallocation  of 
space  in  the  free  dynamic  memoc"  of  the  executing  task.  The  core 
allocation  routines  are: 

•  The  Allocate  Block  Routine  ($a:..BLK)  ,  which  provides  the 
interface  between  the  executing  task  and  the  other  core 
allocation  routines.  That  is,  the  executing  task  is  provided 
all  the  services  of  the  core  allocation  routines  by  simply 
calling  the  'JALBLK  routine,  or  those  routines  that  call  the 
$ALBLK  routine. 

•  The  Get  Core  Routine  ($GTCOR) ,  which  is  always  called  by  the 
$ALBLK  routine  to  perform  the  necessary  processing  to  effect 
allocation  of  the  requested  memory  space  from  the  free  dynamic 
memory. 

•  The  Request  Core  Bloc^  Routine  ($RQCB) ,  which  is  called  by  the 
$GTCOR  routine  to  allocate  the  requested  memory  space  if  it  is 
available  in  the  free  dynamic  memory. 
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•  The  Write  Page  Routine  (SWRPAG) ,  which  Is  called  by  tht  SGTCOR 
routine  to  transfer  memory  pages  to  the  user's  disk  work  file 
to  free  enough  memory  sp^ce  to  satisfy  the  memory  allocation 
request . 

•  The  Release  Core  Block  Routine  {$RLCB),  which  is  called  by  the 
$GTCOR  routine  to  release  space  previously  allocated  to  a 
memory  page  that  has  been  transferred  to  the  disk  work  file. 

In  addition  to  the  five  core  allocation  routines  mentioned  above, 
there  is  a  sixth  routine  called  the  Extend  Task  Routine  ($EXTSK), 
which  is  accessed  by  the  statistical  module  GTCOS.  The  SEXTSK  routine 
is  called  by  the  $GTCOR  routine  to  extend  the  size  of  the  task  region, 
thus  making  enough  memory  available  in  the  free  dynamic  memory  to 
satisfy  the  allocation  request. 

NOTE 

The  user  should  not  confuse  the 
statistical  module  GTCOS  with  the 
nonstatistlcal  module  GTCOR.  Both  of 
these  modules  are  called  by  references 
to  the  entry  point,  SGTCOR.  In  order 
for  $GTCOR  to  call  SEXTSK,  the  user 
would  have  had  to  define  and  Initialize 
W$$KST  in  the  source  program  at 
task-build  time.  When  W$$KST  is 
undefined,  the  user  gets  the 
nonstatistlcal  module  GTCOR  by  default 
(see  Table  8-1) . 

The  processing  performed  by  the  core  allocation  routines  is  described 
i.T  the  following  sections. 


8.3.1   Allocate  Block  Routine  (SALBLK) 

The  $ALBLK  routine  determines  whether  a  block  of  memory  storage  can  be 
allocated  from  the  free  dynamic  memory.  If  so,  the  SALBLK  routine 
clears  (zeroes)  the  allocat'id  block  and  returns  the  resident  memory 
address  of  the  block  to  the  calling  task.  If  there  is  insufficient 
space  in  the  free  dynamic  memory,  the  requested  block  cannot  be 
allocated.  In  this  case,  the  $ALBLK  routine  sets  the  error/severity 
code  E$R4,S$V2  in  Register  1,  the  address  of  the  argument  block  SFRHD 
(free  memory  header)  in  Register  2,  and  calls  the  user's  SERMSG 
routine  (see  Sertlon  S.l.lj. 

To  use  the  SALBLK  routine: 

•  Input,  in  Register  1,  the  size  (number  of  bytes  less   than   or 
equal  to  512(10)1  of  the  memory  storage  block  to  be  allocated. 

•  Include  the  statement 

CALL  SALBLK 
in  the  source  program. 
If  allocation  is  successful,  the  output  from  the  SALBLK  routine  is 

RO  =  the  dynamic  memory  address  of  the  allocated,  cleared,  block 
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and  control  returns  to  the  caller 
user's  $ERMSG  routine  Is  called. 


If  allocation  is  unsuccessful,  the 


The  Interaction  of  the  $ALBLK  routine  with  the  user's  task  and  other 
virtual  memory  management  routines  is  diagrammed  in  Figure  8-2  and 
described  briefly  below. 
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Figure  8-2   General  Block  Diagram  of  the  SALBLK  Routine 

In  addition  to  the  user's  task,  the  SALBLK  routine  is   called   by   the 
following  virtual  memory  management  routines: 

•  Initialize  Virtual  Memory  Routine  (SiNIVM),  which  calls  $ALBLK 
to  allocate  initial  blocks  of  dynamic  memory  to  enable  page 
swapping  between  disk  and  memory  storage. 

•  Convert  Virtual  to  Real  Address  Routine  ($CVRL) ,  which  calls 
SALBLK  to  allocate  a  block  of  dynamic  memory  for  a  virtual 
page  block.  A'.-^ 

•  Allocate  Virtual  Memory  Routine  (SALVRT),  which  calls  SALBLK 
to  allocate  a  memory  page  block  for  a  virtual  page  block  that 
is  to  be  swapped  from  memory  to  disk  storage. 
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The  SALBLK  routine  always  calls   the   Get   Core   Routine   ($GTCOR)   to 
allocate  the  requested  memory  block,  as  follows: 

•  Request  allocation  from  the  free  dynamic  memory. 

•  If  the  request  is  not  met,  attempt  to  extend  the  task  region 
to  Increase  the  size  of  the  free  dynamic  memory. 

•  If  the  task  cannot  be  extended,  swap  unlocked  pages  from 
memory  storage  to  disk  to  deallocate  memory  apace  for 
real  location. 
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8.3.2   Get  Core  Routine  SGTCOR  (GTCOR) 

The  SGTCOR  routine  (defined  In  the  nonsta t I st leal  module  GTCOR) 
attempts  to  allocate  requested  dynamic  memory  blocks  In  two  ways: 

•  Allocation  from  the  currently   available   space   In   the   free 
dynamic  memory. 

•  Swapping  unlocked  paqe  blocks  from  dynamic  memory  to   disk   to 
free  previously  allocated  memory  space  for  reallocation. 

To  call  the  SGTCOR  routine: 

•  Input,  In  Register  1,  the  size  (number  of  bytes  less   than   or 
equ^l  to  512(10);  of  the  dynamic  memory  block  to  be  allocated. 

•  Include  the  statement 

CALL  ?GTCOR 
In  the  source  program. 
The  outputs  from  the  SGTCOR  routine  are: 

•  RO  =  the  memory   address   of   the   dynamic   memory   block.   If 
al  located . 

•  Condition  Code: 

C  bit  =  clear  If  the  allocation  was  successful, 

C  bit  =  set  If  the  allocation  failed. 

The  Interaction  of  the  SGTCOR  routine  with  other   system   library   and 
virtual   memory   management   routines  is  diagrammed  in  Figure  8-1A  and   | 
described  briefly  below. 

The  SGTCOR  routine  is  always  called  by  the  Allocate  Block  Routine 
(SALBLK) .  The  SGTCOR  routine  calls  the  SSAVRG  routine  to  save  and 
subsequently  restore  registers  3  -  5  of  the  caller. 
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General  Block  Diagram  of  the  $GTCOR  Routine 
(nonstat 1st  leal  module  GTCOR) 


The  system  library  Request  Core  Block  Routine  (Sr^QCB),  described  In 
Chapter  7,  is  called  to  determine  whether  «nouc,h  free  dynamic  memory 
space  is  currently  available  to  satisfy  the  aliocatlon  req-iest.  If 
so,  the  SGTCOR  routine  returns  the  memory  address  of  the  resident 
block  to  the  caller. 
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If  the  requested  block  cannot  be  allocated  from  tne  current  free 
dynamic  memory,  the  $GTCOR  routine  searches  for  the  unlockiud  [  ;■  . 
currently  resident  In  memory.  If  any  unlocked  pages  are  found,  •J.f 
least  recently  used  (LRU)  paqe  Is  released,  and  its  memory  space  is 
allocated  to  the  new  page.  If  an  unlocked  page  cannot  be  found,  the  C 
bit  Is  set,  Indicating  a  failure  to  find  an  unlocked  page,  and  control 
is  returned  to  the  caller. 

When  an  LRU  p^ge  is  found,  the  SGTCOR  routine  checks  the  page  to  see 
if  it  has  been  written  into.  If  so,  the  Write  Page  Routine  (SWRPAG) 
Is  called  to  write  the  page  to  the  disk  work  file.  The  system  libraiy 
Release  Core  Block  Routine  (SRLCB),  described  in  Chapter  7,  Is  called 
to  lelease  the  page  and  the  Request  Core  Block  Routine  (SRQCB)  Is 
called  to  allocate  the  page.  The  memory  address  of  the  allocated  page 
is  returned  in  RO  to  the  caller.  If  the  SGTCOR  routine  Is  not  able  to 
obtain  sufficient  mer.ory  for  the  requested  block,  the  C  bit  In  the 
Condition  code  is  set  and  control  Is  returned  to  the  caller. 


8.3.2.1  Get  Core  Routine  SGTCOR  (GTCOS)  --  The  SGTCOR  routine 
(accessed  by  the  statistical  module  GTCOS)  attempts  to  allocate 
requested  dynamic  memory  blocks  In  three  ways: 

•  Allocation  from  the  currently   available   space   In   the   free 
dynamic  memory. 

•  Extension  of  the  task  region  to  Increase  the  size  of  the   free 
dynamli.  remory  to  accommodate  the  allo^itlon  request. 

•  Swapping  unlocked  page  blocks  from  dynamic  memory  to   disk   to 
free  previously  allocated  memory  space  for  reallocation. 

To  call  the  SGTCOR  routine: 

•  Input,  in  register  1,  the  size  (number  of  bytes  less   than   or 
equal  to  512(10)  of  the  dynamic  block  memory  to  be  allocated. 

•  Include  the  statement 

CALL  SGTCOR 
In  the  source  program. 
The  outputs  from  the  SGTCOR  routine  are: 

•  RO  =  the  memory  address  of  the  dynamic  block,  if  allocated. 

•  Condition  Code; 

C  bit  »  clear  if  the  allocation  was  successful. 

C  bit  -  set  if  the  allocation  failed. 

The  Interaction  of  the  SGTCOR  routine  with  -^fier  system  library  and 
virtual  memory  management  routines  Is  dld'-,rammed  In  Figure  8-3B  and 
described  briefly  below. 

The  SGTCOR  routine  Is  always  called  by  the  Allocate  Block  Routine 
(SALBLK) .  The  SGTCOR  routine  ca^ Is  the  SSAVRG  routine  to  save  and 
subsequently  restore  registers  3-5  of  the  caller. 
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Figure  8-3B   General  Block  Diagram  of  the  $GTCOR  Routine 
(statistical  module  GTCOS) 


The  system  library  Request  Core  Block  Routine  ($RQCB) ,  described  In 
Chapter  7,  is  called  to  determine  whether  enough  free  d/namic  memory 
space  is  currently  available  to  satisfy  the  allocation  request.  If 
so,  the  $GTCOR  routine  returns  the  memory  address  of  the  resident 
block  to  the  caller. 

If  the  requested  block  cannot  be  allocated  from  the  current  free 
dynamic  memory,  the  $GTCOR  routine  calls  the  Extend  Task  Routine 
(SEXTSK)  to  determine  whether  the  task  region  can  be  extended  to  make 
available  the  requested  space  in  the  free  dynamic  memory.  If  so,  ^he 
SGTCOR  rou'^ine  returns  the  memory  address  to  the  caller. 
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If  the  task  region  cannot  be  extended,  the  SCTf^^OR  routine  searches  for 
unlocked  pages  currently  resident  In  memorv-  IE  any  unlocked  pages 
are  found,  the  "least  recently  used"  (LRU)  paqe  Is  released,  and  ' ts 
memory  space  Is  -located  to  the  new  paue. 

When  an  LRU  page  Is  found,  the  SGTCOR  routine  checks  the  page  to  see 
If  It  has  been  written  Into.  If  so,  the  Write  Page  Routine  ($WRPAG) 
is  called  to  write  the  page  to  the  disk  work  file.  The  system  )irrary 
Release  Core  Block  Routine  (SRLCB),  described  in  Chapter  7,  Is  '-.tiled 
to  release  the  page  and  the  Request  Core  Block  Routine  {SRQCB)  Is 
called  to  allocate  the  page.  The  memory  address  of  the  allocated  page 
Is  returned  In  RO  to  the  caller.  If  the  SGTCOR  routine  Is  not  able  to 
obtain  suffli  '.eni.  memory  for  the  requested  block,  the  C  bit  In  the 
Condition  Code  Is  set  and  control  is  returned  to  the  caller. 


8.3.3   Extend  Task  Routine  (SEXTSK) 

The  $f:xtsk  routine  extends  the  current  region  of  the  tasik  to  Increase 
the  amount  of  available  memory  for  allocation.  The  task  region  is 
extended  by  the  specified  size  rounded  to  the  next  32-word  boundary. 

To  call  the  SEXTSK  routine: 

•  Input,  In  Rec/lster  1,  the  size  (number  of  bytes  less   than   or 
equal  to  512(10))  of  the  memory  storage  block  to  be  allocated. 

•  Include  the  statement 

CALL  SEXTSK 

in  the  source  program. 

All  registers  of  the  caller  are  preserved  except  Rl,  which  contains 
output  from  the  SEXTSK  routine,  as  follows: 

•  Rl  =  actual  extension  size  (requested   size   rounded   to   next 

32-word  boundary) • 

•  Condition  Code: 

C  bit  =  clear  If  extension  was  successful. 

C  bit  =  set  if  extension  failed. 

The  interaction  of  the  SEXTSK  routine  with  the  SGTCOR  routine  (in 
statistical  module  GTCOS)  is  shown  in  Figure  8-4  and  described  below. 

The  SEXTSK  routine  Is  called  by  the  Get  Core  Routine  (SGTCOR)  when 
there  is  insufficient  space  in  the  current  free  dynamic  memory  to 
satisfy  a  meniory  block  allocation  request.  The  SEXTSK  routine  rounds 
the  requested  extension  size  to  the  next  32-word  boundary.  If  there 
Is  enough  memory  space  available,  the  task  region  is  extended  and  the 
total  amount  of  the  extension  is  returned,  in  Register  1,  to  the 
SGTCOR  routine.  If  the  task  region  cannot  be  extended,  the  SEXTSK 
routine  sets  the  C  bit  in  the  Condition  Code  and  returns  to  the  SGTCOR 
rout  Ine . 

The  SEXTSK  routine  may  be  called  directly  by  the  user.  The  routine  is 
called  by  the  Initialize  Dynamic  Memory  Routine  (SINIDM),  described  in 
Chapter  7. 
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Figure  8-4   General  Block  Diagram  of  the  $EXTSK  Routine 


8.3.4  Write  Page  Routine  ($WR?AG) 

The  §WRPAG  routine  effects  the  transfer  of  a  memory  page  to  the  disk 
work  file. 

To  call  the  $WRPAG  routine: 

•  Input,  in  Register  2,  the  dynamic  memory  address  of   the   page 
to  be  transferred. 

•  Include  the  statement 

CALL  SWRPAG 

in  the  source  program. 

The  output  from  the  $WRPAG  routine  is  the  transferred  page,  with 
successful  transfer  indicated  by  a  cleared  C  bit  in  the  Condition  Code 
when  control  returns  to  the  caller.  If  the  page  transfer  is 
unsuccessful,  the  $WRPAG  routine  sets  the  error/severity  code 
E$R73,S$V2  in  Register  1,  and  calls  the  user's  $ERMSG  routine  (see 
Section  8.1.1) . 

The  interaction  of  the  $WRPAG  routine  with  the  SGTCOR  routine  is  shown 
in  Figure  8-5  and  described  below. 

The  $WRPAG  routine  is  called  by  the  Get  Core  Routine  ($GTCOR)  when  a 
resident  memory  page  that  has  been  written  into  is  to  be  transferred 
to  the  user's  disk  work  file. 
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« 

The  SWRPAG  routine  calls  the  SSAVVR  routine  to  save   and   aubsequently 
restore  the  caller's  registers  0-2.   The  routine  then: 

•  Sets  up  the  disk  work  file  address  of  the  page  to  be 
transferred . 

•  Initiates  the  page  writing  operation. 

•  Checks  the  status  of  the  write  operation. 

•  Indicates  a  successful  transfer  (clears  the  C  bit  in  the 
Condition  Code)  and  returns  control  to  the  SSAWR  routine,  or 
calls  the  user's  SERMSG  routine  if  a  fatal  work  file  I/O  error 
prevented  the  page  transfer. 
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Figure  8-5   General  Block  Diagram  of  the  $WRPAG  Routine 
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e.4   VIRTUAL  MEMORY  ALLOCATION  ROUTINES 

The  virtual/memory,  diiocdtion  routines  manage  the  allocation  of  disk 
and  memory  storage  to  enable  page  swapping  from  the  free  dynamic 
memory  to  the'uaer's  disk  work  file.  There  are  three  virtual  memory 
allocation  routines: 

•  The  Allocate  Virtual  Memory  Routine  (SALVRT),  which  allocates 
disk   and'  memory   page   blocks,   maintains   page   control  and 

'  address  tables,  and  interfaces  the  executing  task  and  the  core 
allocation  and  page  management  routines. 

•  The  allocate  Small  Virtual  Block  Routine  (SALSVB),  which 
allocates  smtoll  page  blocKS  of  disk  and  memory  storage  within 
large  page  blocks  to  enable  efficient  usage  of  storage.  The 
$ALSVB  rodtine  interfaces  with  the  $ALVRT  routine  and  page 
management  routines  to  ensure  address  and  status  control  of 
small  pages  in  memory  and  disk  storage. 

•  The^Request  Virtual  Core  Block  Routine?  (SROVCB),  which  manages 
page  block  allocation  on  the  user's  disk  work  file  when  it  is 
called  by  the  SALVRT  routine. 

The  processing  performed  by  th"  virtual  memory  allocation  routines  Is 
dercribed  in  the  following  sections. 


8.4.1   Allocate  Virtual  Memory  Routine  ($ALVRT) 

The  $ALVRT  routine  determines  whether  a  page  block  of  virtual  storage 
can  be  allocated  on  the  user's  disk  work  file.  If  so,  the  SALVRT 
routine  ensures  that  an  equal  amount  of  memory  storage  is  allocated, 
updates  page  control  and  address  tables,  and  returns  the  disk  and 
memory  addresses  of  the  allocated  page  blocks  to  the  caller.  If  the 
SALVRT  routine  cannot  allocate  the  requested  storage,  the 
error/severity  code  ESR76,SSV2  is  stored  in  Register  1  and  the  user's 
SERMSG  routine  (see  Section  8.1.1)  is  called. 

To  call  the  SALVRT  routine: 

•  Input,  in  Register  1,  the  size  (number  of  bytes  less   than   or 
equal  to  512(10))  of  the  disk  storage  block  to  be  allocated. 

•  Include  the  statement 

CALL  SALVRT 
in  the  source  program. 
NOTE:   The  maximum  size  of  a  page  block  is  512(10)  bytes. 
If  allocation  is  successful,  the  SALVRT  routine  returns  the  outputs: 

•  RG  =  memory  address  of  allocated  page  Jlock. 

•  Rl  =  disk  address  of  allocated  page  block. 

The  SALVRT  routine  calls  the  SSAVRG  routine  to  save  and  subsequently 
restore  registers  3  -  5  of  the  caller.   Register  2  is  destroyed. 

The  interaction  of  the  SALVRT  routine  with  the  user's  task  and  othei 
virtual  memory  management  routines  is  shown  in  Figure  8-6  and 
described  below. 
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In  addition  to  the  user's  task,  the  SAI.VRT  routine  is  called  by 
Allocate  Small  Virtual  Block  Routine  ($ALSVB). 


the 


The  $ALVRT  routine  calls  the  Request  Virtual  Core  Block  Routine 
(SRQVCB)  to  determine  whether  the  requested  storaqe  can  be  allocated 
on  the  disk  work  file.  If  not,  a  fatal  error  is  signalled  and  the 
SALVRT  routine  calls  the  user's  SERMSG  routine. 
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Figuie  8-6   General  Block  Diagram  of  the  $ALVRT  Routine 
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If  the  disk  storage  cat\  be  allocated,  the  $ROVCB  routine  return*  th« 
disk  pacje  block  address  to  the  SALVRT  routine,  which  determines 
whether  a  page  block  of  space  Is  available  in  momory.  If  not,  the 
Allocate  Block  Routine  (SALBLK)  is  called  to  allocate  a  page  block. 
The  SALVRT  routine  then  calls  the  Convert  Virtual  to  Real  Address 
Routine  (SCVRL)  to  convert  the  virtual  address  to  a  memory  address. 

The  SALVRT  routine  calls  the  Wrlte-marked  Page  Routine  (SWRMPO)  to  set 
the  "written  into"  flag  of  the  memory  page. 


8.4.2   Allocate  Small  Virtual  Block  Routine  (SALSVB) 

The  SALSVB  routine  allocates  small  page  blocks  within  large  page 
blocks  of  rllsk  and  memory  storage.  Thus,  the  routine  accommo'latea 
varlab'»»  user  allocation  size  requirements  and  minimizes  wasted 
storage  space. 

The  SALSVB  routine   initially   allocates   a   large   page   block,  then 

performs   sub -al locat Ion   of   requested   small  blocks  within  ihe  large 

block.  When  the  space  wlthlr  a  large  block  is  exhausted,  a  new  large 
block  I?  allocated  by  the  SALSVB  routine. 

To  call  the  SALSVB  routine: 

•  Define  the  following  in  f-he  source  program: 

NSDLGH  »  "  512. 

Normally,  this  is  the  size  of  a  large  memory   block.    In   any 
case.  It  must  be  less  than  or  equal  to  512(10). 

•  Specify,  in  Register  I,  the  size   of   the   page   block   to   be 
allocated,  where: 

Rl  ■  zero  (0)  to  force  the  allocation  of  a  large  virtual   pago 
block  on  the  first  call  to  SALSVB. 

Rl  ■  a  value  less  than  or  equal  to   512   (10)   specifying   the 
size,  in  bytes,  of  the  small  pa^e  to  be  allocated. 

NOTE:  rhe  maximum  size  of  a  page  block  is  512(10)  bytes. 

•  Include  the  statement 

CALL  SALSVB 
in  the  source  program. 
The  outputs  from  the  SALSVB  routine  are: 

•  RO  =  the  dynamic  memory  address  of  the  allocated  page  block. 

•  Rl  =•  the  virtual  address  of  the  allocated  block. 

Registers  3-5  are  preserved.   Register  2  Is  destroyed. 

The  interaction  of  the  SALSVB  routine  with  other  virtual  memory 
management  routines  is  diagrammed  In  Figure  8-7,  .ind  described  briefly 
below. 
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Figure  8-7  General  Block  Diagram  of  the  $ALSVB  Routine 


Hhen  a  small  page  block  is  to  be  allocated  within  an  existing  large 
page  block,  the  $.ALSVB  routine  calls  the  Convert  victual  to  Real 
Address  Routine  ($CVRL)  to  perform  the  following: 
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•  Locate  the  allocated  large  page,  if  it  is  memory  residbnr.   If 
not  resident,  read  the  page  from  disk  to  memory. 

•  Convert  the  virtual  page  address  to  a  memory  page  address. 

•  Transfer  the  large  page  block  from   .sk  into  the  large  memory 
page  block. 

The  $ALGVB  routine  calls  the  Write-marked  Page  Routine  ($WRMPG)  to  set 
the  "written  into"  flag  of  the  allocated  memory  page. 

When  a  large  page  blocK  is   to  be   allocated,   the  Allocate  Virtual 
Memory  Routine  (SALVRT)  is  called  to  effect: 

•  Disk  and  dynamic  memory  allocation  of  the  requested  large  page 
block. 

•  Virtual  address  conversion  to  a  memory  address. 

•  Transfer  of  the   large  block,   if   necessary,   from  disk   to 
dynamic  meirory. 

•  Setting  the  "written  into"  flag  of  the  allocated  page  block. 


8.4.3  Request  Virtual  Core  Block  Routine  ($RQVCB) 

The  $RQVCB  routine  manages  page  block  allocation  on  the  user's  disk 
work  file.  The  $RQVCB  routine  is  called  by  the  Allocate  Virtual 
Memory  Routine  (SALVRT)  when  a  usei's  task  has  requested  allocation  of 
a  page  block  of  a  maximum  of  512  (10)  bytes  in  length. 

The  interaction  of  the  $RQVCE>  routine  with  the  $ALVRT  routine  is 
diagrammed  in  Figure  8-8  and  described  briefly  below. 

The  $RQVCB  routine  rounds  the  requested  number   of  bytes  up   to   thr 

nearest  word.   If  the  rounded  value  crosses  a  disk  block  boundary,  the 

$RQVCB  routine  allocates  the  page  block  beginning  at  the  next  disk 
block . 

If  allocation  is  successful,  the  $RQVCB  routine  clears  the  C  bit  in 
the  Condition  Code  and  returns  the  disk  address  of  the  allocated  page 
to  the  $ALVRT  routine. 

If  allocation  is  not  successful,  the  $RQVCB  routine  sets  the  C  bit  in 
the  Condition  Code  and  returns  control  to  the  $ALVRT  routine.  '''wo 
conditions  cause  allocation  failure: 

•  There  is  no  more  disk  storage  space  available. 

•  A  page  block   size  greater   than   512   (10)   bytes  has  been 
requested . 
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Figure  8-8   General  Block  Diagram  of  the  $RQVCB  Routine 


8.5   PAGE  MANAGEMENT  ROUTINES 

The  page  management  routines  perform  the  processing  required  to 
control  page  swapping  between  dynamic  memory  and  disk  file  storage. 
Required  processing  includes  address  conversion,  page  location,  page 
transfer  from  disk  to  iiemory,  and  page  status  handling,  such  as 
time-stamping,  flagging  as  "written  into",  and  locking  and  unlocking 
memory  pages.   The  page  management  routines  are; 
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•  The  Convert  and  Lock  Page  Routine  ($CVLOK) ,  which  convertB  a 
virtual  address  to  a  dynamic  memory  address  and  locks  the  page 
in  memory  when  called  by  the  user's  task. 

•  The  Convert  Virtual  to  Real  Address  Routine  ($CVRL) ,  which 
converts  a  virtual  address  to  a  dynamic  memory  address  when 
called  by: 

•  the  user  task. 

•  the  Allocate  Virtual  Memory  Routine  (SALVRT)  when  a  new 
disk  page  has  been  allocated. 

•  the  Convert  and  Lock  Page  Routine  (SCVLOK),  when  a  page 
address  Is  to  be  converted  and  the  page  Is  to  be  locked 
in  memory. 

•  The  Read  Page  Routine  ($RDPAG) ,  which  Is  called  by  the  SCVRL 
routine  to  transfer  a  page  from  the  user's  disk  work  file  to 
dynamic  memory. 

•  The  Find  Page  {$FNDPG) ,  which  determines  whether  a  virtual 
page  is  resident  in  dynamic  memory  when  called  by: 

•  the  $CVRL  routine. 

•  the  Lock  Page  Routine  ($LCKPG)  , 

•  the  Unlock  Page  Routine  (SUNLPG)  . 

•  the  Wrlte-marked  Page  Routine  ($WRMPG) . 

•  The  Write-marked  Page  Routine  (§WRMPG) ,  which  sets  the 
"written  into"  flag  of  memory  pages  when  called  by  the  user  or 
by  the  $ALVRT  and  SALSVB  virtual  memorv  allocation  routines. 

•  The  Lock  Page  Routine  ($LCKPG) ,  which  Is  called  by  the  SCVLOK 
routine  and  the  user's  task  to  set  a  lock  byte  In  a  memory 
page  to  prevent  its  being  swapped  from  memory  to  the  disk 
file. 

•  The  Unlock  Page  Routine  (SUNLPG),  which  Is  called  by  the 
user's  task  to  clear  a  lock  byte  in  a  memory  page  to  allow  It 
to  be  swapped  to  disk  storage  to  free  memory  space  for 
reallocation. 

The  processing  performed  by  the  page  management  routines  is  described 
in  the  following  sections. 


8.5.1   Convert  and  Lock  Page  Routine  (SCVLOK) 
The  SCVLOK  routine  performs  two  functions: 

•  Converts  a  virtual  address  to  a  memory  address, 

•  Locks  the  page  in  memory. 
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To  call  the  SCVLOK  routine: 

•  Specify,  in  Register  1,  the  virtual  address  to  be  converted. 

•  Include  the  statement 

CALL  SCVLOK 
in  the  source  program. 
Outputs  from  the  SCVLOK  routine  are: 

•  RO  -  converted  memory  address. 

•  Rl  >  virtual  address. 

•  Condition  Code: 

C  bit  ■  clear  if   the   address   was   converted   and   the   page 
locked . 

C  bit  "  set  if  address  conversion  or  page  locking  failed. 

The  contents  of  R2  are  preserved.   Registers  3-5   are   preserved   bv 
the  SCVRL  routine. 

The  interaction  of  the  SCVLOK  routine  with  the  calling  task  and   other 
page  management  routines  is  Siiown  in  Figure  8-9. 

The  SCVLOK  routine  calls: 

•  The  Convert  Virtual  to  Real  Address  Routine  (SCVRL)  to  convert 
the  virtual  address  to  a  memory  address. 

•  The  LOCK  Page  Routine  (SLCKPG)  to  lock  the  page  in  memory. 
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$C  VRL  CONVERT  VIRTUAL  TO  REAL  AOORESS 


V  ^*^^  ) 


SCVLOK 


CjIISCVRL  to 
con«ri  virtual 
to  m«morv 
iddrvM 


</  SCVRL  J 


Call  SLCKPG 
to  lock  ptqu 
in  cor« 


SLCKPG 


Sat  C  bit, 
return 


CItir  Cbit   Mt 
RO  ■■  memory 
addms.  Mt 
Rl   =  virtual 
address,  return 


Figure  8-9   General  Block  Diagram  of  the  SCVLOK  Routine 

8.5.2  Convert  Virtual  to  Real  Address  Routine  ($CVRL) 

The  $CVRL  routine  converts  a   virtual   address   to   a   dynamic   memory 
address. 

To  call  the  SCVRL  routine: 

•  Input,  in  Register  1,  the  virtual  address. 

•  Include  the  statement 

CALL  SCVRL 
in  the  source  program. 
The  output  from  the  SCVRL  routine  is: 
RO  =»  memory  address. 
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The  $SAVRU  routine  is  called  to  save  and   lestore   reqisters   J 
Register  1  is  unchanged.   Registec  2  is  destroy-K). 


5. 


The  1  tecaction  of  the  $CVRL  routine  with  the  Ciller  and  other  virtual 
memory  management  routines  is  shown  in  Kici  jie  8-10  and  described 
briefly  below. 

The  $CVRL  routine  may  be  called  by  the  user's  task,  and  the  following 
routines: 

•  Allocate  Virtual  Memory  Routine  ($ALVKT) ,  when  a  new  disk  page 
has  been  allocated. 


Convert  and  Lock  Page  Routine   ($CVLOK),   when   the   executing 
task   has   specified  tint  a  virtual  address  is  to  be 
to  a  memory  address  and  the  page  is  to  be  locked 


conver  ted 
in  memory. 


The  $CVRL  routine  calls  the  Find  Page  Routine   (SKNDPG)   to   determine 
whether   the  specified  page  is  resident  m  memory.   If  so,  the  virtual 
is  converted  to  a  memory  address,  which   is   returned   to   the 
If  the  page  is  not  in  memory,  the  Allocate  Block 
($ALBI.K)  is  called  to  allocate  a  memory  page  block.   The  $CVRL 
then  calls  the  Read  Page  Routine  ($RDPAU)  to  transfer  the  disk 

The  page  address  is   then   converted   to   a 


address 
caller . 
Routine 
routine 
page  into  dynamic  memory 


men\ory   address.   The  memory  address  of  the  specified  word  in  the  page 
and  control  is  transferred   to   the   SSAVRG   routine, 
3-5  and  returns  to  the  caller. 


is  stored  in  RO, 

which  restores  registers 


^i 


Talk 


C*ll«r      1  ■  SALVRT 
/  »  tCVLOK 


^ 


$CVRL 


_L 


SSAVRG 


..ill  SFNOPG 
to  f'ml  ^tcft 


Convert  address. 
j«t  RO  '  m«mo'y 
»<1f)re«,  feturn 


JSAVHG 


J         SFNOPG  j 


Call  SALBLK 
10  *ll(x:*t« 
memo'y  page 
block 


< 


SALBLK 


Call  SROPAG 
to  read  disk 
patji'  nio 
memofy  page 


$RDPAG 


Figure  8-10   General  Block  Piagram  of  the  $CVRL  Routine 
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8.5.3  Read  Page  Routine  ($ROPAG) 

The  $RDPAG  routine  effects  t.ie  transfer  of  a  disk  page  from  the  work 
file  to  the  dynamic  memory. 

To  call  the  $RDPAG  routine: 

•  Input,  in  Register  0,  the  disk  address  of  tl^e  page  to  be 
transferred. 

r  Include  the  statement 

CALL  $RDPAG 

in  the  source  program. 

The  output  from  the  $RDPAG  routine  is  the  transferred  page,  indicated 
by  a  cleared  C  bit  in  the  Condition  Code  when  control  returns  to  the 
caller.  If  the  page  transfer  is  unsuccessful,  the  $RDPAG  routine  sets 
che  error/severity  code  E$R73,S$V2  in  Register  1  and  calls  the  user's 
$ERMSG  routine  (see  Section  8.1.1). 

The  interaction  of  the  SPDPAG  routine  with  the  task  and  the  $CVRL 
routine  is  shown  in  F^  lure  6-1.1  and  described  below. 

The  $RDPAG  routine  is  called  by  the  Convert  Virtual  to  Real  Address 
Routine  ($CVRL)  when  a  disk  page  is  to  be  transferred  to  dynamic 
memory. 

The  $RDPAG  routine  calls  the  $SAWR  routine  to  save  and  subsequently 
restore  the  caller's  registers  0-2.   The  routine  then: 

•  Sets  up  the  address  of  the  page  to  be  transferred. 

•  Initiates  the  page  reeding  operation. 

•  Checks  the  status  of  the  read  operation. 

•  In'-.icates  a  succssful  transfer  (clears  the  C  bit  in  the 
Condition  Code)  and  returns  control  to  the  $SA\,'Vr'  routine,  or 
calls  the  user's  $ERMSG  routine  if  a  fatal  work  file  I/O  error 
prevented  the  paae  transfer. 
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Figure  8-11  General  Block  Diagram  of  the  $PDPAG  Routine 


8.5.4  Find  Page  Routine  ($PNDF^) 

The  $FNDPG  routine  searches  an  internal  page  address  list  to  determine 
whether  a  virtual  page  has  already  been  t  ansferreo  into  an  allocat'jd 
memory  page  block. 
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To  call  the  $FNOPG  routine: 

•  Specify,  in  Register  1,  the  virtual  page  address, 
e   Include  the  statement 

CALL  SFNDPG 
In  the  source  r^o9i^<>'><- 
The  outputs  from  the  $PNOPG  routine  are: 

•  RO  -  the  memory  page  block   address   in  which   the   page   is 
resident. 

•  Condition  Code: 

C  bit  -  cleared  if  page  is  resident. 

C  bit  >  set  if  page  was  not  found. 

The  content  of  Register  1  is  not  changed. 

The  interaction  of  the  $FNDPG  routine  with  the  user's  task  and  the 
page  management  routines  is  shown  in  Figure  8-12  and  described  below. 

The  $FNDPG  routine  is  called  by  the  following  virtual  memory 
management  routines: 

•  Convert  Virtual  to  Real  Address  Routine  ($CVRL)  when  a  virtual 
address  is  to  be  converted  to  a  memory  address. 

•  Lock  Page  Routine  ($LCKPG)  when  a  memory  page  is  to  be   locked 
in  core  memory. 

•  Unlock  Pac,e  Routine  ($UNLPG)  when  a  locked  memory  page   is   to 
be  unlocked. 

e  Write-marked  Page  Routine  ($WRMPG)   when   the   "written   into" 
flag  is  to  be  set  in  a  memory  page. 

The  $FNDPG  routine  determines  whether  the  specified  page  is  resident 
in  the  task's  dynamic  memory.  If  so,  the  page  is  time-stamped,  its 
page  block  address  is  set  in  Register  0,  the  C  bit  in  the  Condition 
Code  is  cleared,  and  control  returns  to  the  caller.  If  the  page  is 
not  resident  in  memory,  the  C  bit  in  the  Condition  Code  is  set,  and 
control  returns  to  the  caller. 
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PINO  PAGE     $FNDPQ 
WRITE  MARKED  PAGE     $WRMPG 
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Figure  8-12  General  Block  Diagram  of  the  $FNDPG  Routine 


8.5.5  Write -marked  Page  Routine  ($NRMPG) 

The  SWRMPG  routine  sets  the  "written  into"  flag  of  the  apecified   page 
in  dynamic  memory. 

To  call  the  $WRMPG  routine: 

•  Specify,  in  Register  1,  the  virtual  address  in  the  page. 

•  Include  the  statement 

CALL  $WRMPG 

in  the  source  program. 

The  output  from  the  SWRMPG  routine  is  a  Condition  Code  setting: 

C  bit  =  cleared  to   indicate   that   the  page  was  write  marked 
successfully. 

C  bit  =  set  to  indicate  that  the  specified  memory  page  was   not 
resident  in  the  task's  free  dynamic  memory. 
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The  interaction  of  th<»  $WRMPG  routine  with  the  caller  and  virtual 
memory  management  routines  is  shown  in  Figure  8-13  and  described 
below. 

The  $WRMPG  routine  la  called  by  the  following  virtual  memory 
management  routines: 

•  Allocate  Virtual  Memory  Routine  (SALVRT)  when  a  disk  page   has 
been  allocated  in  dynamic  memory. 

•  Allocate  Small  Virtual  Block  Routine   (SALSVB)   when   a   small 
page  block  has  been  allocated  within  a  large  page  block. 

The  $WRMPG  routine  calls  the  $SAVVR  routine  to  save  and  subsequently 
restore  registers  0  -  2  of  the  caller. 

The  Find  Page  Routine  (SFNDPG)  is  called  to  determine  whether  the 
specified  page  is  resident  in  the  task's  memory.  If  not,  the  C  bit  in 
the  Condition  Code  is  set,  .ind  control  is  transferred  to  the  SSAWR 
routine  to  restore  registers  0-2  and  return  to  the  caller.  If  the 
page  is  resident  in  memory,  its  "written  into"  flag  is  set,  the  C  olt 
in  the  Condition  Code  cleared,  and  control  Is  transferred  to  the 
$SAVVR  routine  to  restore  RO  -  R2  and  return  to  the  caller. 
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Figure  8-13  General  Block  Diagram  of  the  $WRMPG  Routine 
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8.5.6  Lock  Pag*  Routine  ($LCRPG) 


The  $LCKPG  routine  seta  a  locK  byte  In  a  memocy-reBldent  page  to 
prevent  its  being  swapped  from  dynamic  memory  to  the  disk  work  file. 

To  call  the  SLCKPG  routine: 

e   Specify,  in  Register  1,  a  virtual  address  in  t^e   page   to  be 
locked  in  dynamic  memory. 

e   Include  the  statement 

CALL  SLCKPG 

in  the  source  program. 

The  output  from  the  SLCKPG  routine  is  a  Condition  Code  settingt 

C  bit  ■  cleared  if  the  page  was  locked  in  memory. 

C  bit  "  set  if  the  page  was  not  found. 

The  interaction  of  the  SLCKPG  routine  witn  the  task  and  page 
management  routines  is  shown  in  Figure  8-14  and  described  briefly 
below. 

The  SLCKPG  routine  may  be  called  by  the  user's  task  and  by  the  Convert 
and  Lock  Page  Routine  (SCVLOK) . 

The  SLCKPG  routine  calls  the  SSAVVR  routine  to  Save  anJ  subsequently 
restore  the  caller's  registers  C  -  2. 

The  Find  Page  Routine  (SFNOrG)  Is   called   to   determine   whether  the 

memory  page  Is  reslde-i-.   If  so,  the  page  lock  byle  Is  set,  the  C  bit 

in  the  Condition  Code  Is  cleared  and  control  Is  transferred  to  the 
SSAVVR  routine  to  restore  RO  -  R2  and  return  to  the  caller. 

If  the  specified  page  Is  not  in  memory,  the  C  bit  In  the  Condition 
Code  is  set  and  control  is  returned,  via  the  SSAWR  routine,  to  the 
callT'- . 
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Figure  8-14   General  Block  Diagram  of  the  SLCKPG  Ro'itine 


8.5.7   Unlock  Paqe  Routine  ($UNLPG) 

The  $UNLPG  routine  clears  a  lock  byte  in  a  memory-resident  pa'^e  lo 
allow  t.^e  page  to  be  swapped  from  dynamic  memory  to  the  disk  wirx 
file. 

To  call  the  $UNLPG  routine: 

•  .specif/,  in  Register  1,  the  virtual  address  in  the  page  to   be 
unlocked . 

•  Include  the  statement 

CALL  $UNLPG 
in  the  source  program. 
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The  output  from  the  SUNLPG  routine  is  u   Condition  Code  bit  setting: 

C  bit  =  cleared  if  the  page  was  unlocked. 

C  b.t  "  set  if  the  page  was  not  found. 

The  interaction  of  the  $UNLPG  routine  with  the  task  is  shown  in  Figure 
8-15  and  described  briefly  below. 

The  $UNLPG  routine  '-alls  the  $SAVVR  routine  to  sa"e   and   subsequently 
restore  the  caller's  registers  0-2. 

The  Find  Page  Routine  ($FNDPG)  is  called   to  determine  whether   the 

memory  page   is  resident.   If  so,  the  page  lock  byte  and  the  C  bit  in 

the  Condition  Code  are  cleared  and   control   is   transferred   to   the 

$SA\A/R  routine  to  restore  RO  -  R2  and  return  to  the  caller. 

f  the  specified  page  is  not  in  memory,  the  C  bit  in  the  Condition 
Code  is  set  and  control  is  returned,  via  the  $SAVVR  routine,  to  the 
caller . 


SSAVVR 
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to  find  page 
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and  exit  to  caller 


Figure  8-15  Genaral  Block  Diagram  of  the  $UNLPG  Routine 
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CHAPTER  9 
:UMMARy  PROCEDURES 


The  procedures  for  using  the  system  library  routines  are  summarized  in 
t<?oular  format  In  this  chapter.  These  summaries  are  presented  as 
quick  reference  guide.''  for  users  who  are  familiar  with  the  detailed 
procedures  and  requirements  for  using  individual  routines,  as 
described  in  preceding  chapters  of  this  manual. 


Table  9-1 
Register  Handling  Routines  Summary 


Routine    Name/ 
Mnemonic 

Fun::tion 

Call    Stc-.tement 

Save   All    Registers 
SSAVAL 

Saves/restores    RO    -  R5 

JSR    PC,SSAVAL 

Save    Regis  '•ers    3-5 
$SAVRG 

Saves/restoreK    R3    -  R5 

JSR    R5,SSAVRG 

Save    Registers    0-2 
$^AWR 

Saves/restores    RO    -  R2 

JSR    R2,$SAVVR 

Save    Registers    1-5 
.SAVRl 

Saves/restores    Rl    -   R5 

JSR    R5,     . SAVRl 
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Table  9-2 
Arithmetic  Routines  Summary 


Rout ;  -y   Na-ne/ 
Mne.   ,nlc 

Input   Arguments    and 
Call    Statement 

Outputs 

Integer   Multiply 
SMUL 

RO    •   multipl ier 
Rl    ■   mul tipl Icand 
CALL    SMUL 

Proiuct : 

RO    •   h'  ,h   order    ^^art 
Rl   "   low  order    part 
R2-R5  preserved 

Integer    Dlvlda 
SDIV 

RO    •  dividend 
Rl    ■   divisor 
CALL   SDIV 

RO    •   quotient 
Rl    "    remainder 
R2-R5   preserved 

Double-pr«clslon   Multiply 
SDMUL 

RO   •  multipl  f-^r 
Multipl icand : 
R2  "  high  order    part 
R3  "   low  order    part 
CALL    SDMUL 

Product : 

RO    ■   high   order    part 

Rl    «    low  order    par"- 

C    »   clear 

R4-R5  preserved 

R2-;.3  destroyed 

Double-precision    Divide 
SDDIV 

RO    «   unsigned    divisor 
Dividend : 

Rl   -   high   order    part 
R2   »    low  order    part 

RO    ■    remainder 
Quotient : 

Rl    -   high   order    part 
R2    •    low   order    part 
R3   preserved 

NOTE:      The    arithmetic    rout 
unsigned    results. 

ines    accept    unsigned    in 

puts    and    produce 

Table  9-3 
Input  Data  Conversioi.  Routines  Summary 


Routine   Name/ 

Mnemonic 

Input    Arguments    and    Call    Statement 

Outputs 

Decimal    to 

R3    = 

output    address 

Successful : 

Bir, sry   Double 

R4    = 

number    input    characters 

Converted    number    at    output 

Word 

R5    « 

input   string   address 

sddress : 

.DD2CT 

CALL 

.DD2CT 

Word    1    »   high   order    part 

Word    2    »    low  order    part 

C    «   clear 
Unsuccessful : 

C    «   set 
All    regist»»t3    preserved 

Octal    to 

R3    » 

output    address 

Successful : 

Binary 

R4    " 

number    input   characters 

Converted    number    at    output 

Double 

R5    = 

input    string    address 

address : 

Word 

CALL 

.0D2CT 

Word    1    »   high   order    part 

.0D2CT 

1 

Word    2    "    low  order    part 

C    -   clear 
Unsuccessful : 

C    -    3et 
All    registers    preserved 

(continued  on  next  paqe) 
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Table  9-3  (Cont.) 
Input  Data  Conversion  Routines  Summary 


Routine  Name/ 

Mnemonic 

Input 

Arguments  and  Call  Statement 

Outputs 

Decimal  to 

RO  - 

adJroes  first  Input  byte 

RO  •  address  first  byte 

Binary 

CALL 

SCOTB 

of  next  string 

SCDTB 

Rl  "  converted  number 

R2  •  terminating  character 

R3-R5  preserved 

Octal  to 

RO  - 

address  first  input  byte 

RO  -  address  firJt  byte  of 

Binary 

CALL 

SCOTB 

next  string 

$COTB 

Rl  "  converted  numher 

r.2  "  termlnarlng  character 

R3-R5  preserved 

ASCII  to 

RO  • 

address  first  Input  character 

Successful : 

Radlx-50 

Rl  - 

0  (p«rlod  is  terminating 

RO  -  address  next  input  char- 

SCATS 

character ) 

acter 

Rl  - 

1  (period  is  valid  character) 

Rl  "  converted  Rad<.x-50  value 

CALL 

SCATS 

R2  <•  terminating  character 

C  -  clear 

Unsuccessful : 

R2  "  illegal  character 

C  -  set 

R3-R5  preserved 

ASCII  with 

RO  - 

address  first  Input  character 

Successful : 

Blanks  to 

Rl  • 

0  (period  Is  terminating 

RO  -  address  next  input  char- 

Radix- -0 

character) 

acter 

SCAT5B 

Rl  - 

1  (period  is  valid  character) 

Rl  «  converted  Radlx-50  value 

CALL 

SCAT5B 

R2  •  terminating  character 

C  -  clear 

Unsuccessful : 

R2  •  illegal  character 

C  •  set 

R3-R5  preserved 

Table  9-4 
Output  Data  Conversion  Routines  Summary 


Routine  Name/ 

Mnemonic 

Input 

Arguments  and  Call  Statement 

Outputs 

Binary  Date 

RO  ' 

output  address 

Converted  date  at  out^ut 

Conversion 

Rl  - 

hinary  date 

address 

SCBDAT 

R2  - 

0  (zero  suppress; 

RO  "  next  available 

output 

R2  - 

nonzero  (no  zero  suppress) 

address 

CALL 

SCBDAT 

R3-R5  preserved 
R1-R2  destroyed 

Convert  Binary 

RO  - 

output  address 

Converted  number  at 

output 

To  Decimal 

Rl  - 

binary  number 

address 

Magni  tude 

R2  - 

0  (zero  suppress) 

RO  •  n»>xt  aval  1  able 

output 

SCBDMG 

R2  - 

nonzero  'no  zero  suppress) 

address 

CALL 

SCBDMG 

R3-R5  preserved 
R1-R2  destroyed 

(continued  on  next  page) 
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Table  9-4  (Cont.) 
Output  Data  Conversion  Routines  Summary 


Routine  Name/ 

Mnemon  Ic 

Input 

Arguments  and  Call  Scatement 

Outputs 

Convert  Binary 

RO  - 

output  address 

Converted  number  at 

out  put 

to  Signed 

Rl  • 

binary  number 

address 

Dec  imal 

R2  • 

0  (zero  suppress) 

RO  •  next  available 

output 

SCBDSG 

R2  - 

nonzero  tno  zero  suppress) 

addres:; 

CALL 

SCBDSG 

R3-R5  preserved 
R1-R2  destro/ed 

Convert  Double- 

RO  • 

output  address 

Successful : 

Precision 

Rl  - 

Input  address 

Converted  number  at 

output 

Binary  to 

R2  - 

0  (zero  suppross) 

address . 

Dec Imal 

R2  - 

nonzero  (no  zero  suppress) 

Unsuccessful ; 

SCDDMG 

CALL 

SCDDMG 

String  of  ASCII  anterlsks  at  | 

output  address 

RO  •  next  available 

output 

address 

R  3-RS  presoi ved 

RI-R2  destroyed 

Convert  Binary 

RO  - 

ourpu)-  address 

Converted  number  at 

output 

to  Octal 

Rl  • 

binary  number 

address 

Magnl tude 

R2  - 

0  (zero  suppress) 

RC  «  n.'xL  available 

out  put 

SCBOMG 

R2  - 

nonzero  (no  zero  suppress) 

address 

CALL 

SCBOMG 

R3-n5  preserved 
R1-R2  destroyed 

Convert  Binary 

RO  • 

output  address 

Converted  number  at 

output 

to  Signed 

Rl  « 

binary  number 

address 

Octal 

R2  • 

0  (zero  suppress) 

R J  »  next  aval  1  able 

output 

SCBOSG 

R2  - 

nonzero  (no  zero  suppress) 

address 

CALL 

SCBOSG 

R3-R5  preserved 
R1-R2  destroyed 

Convert  Binary 

RO  • 

output  address 

Converted  byte  at  output 

Byte  to  Octal 

Rl  ■ 

binary  byte 

address 

Magnl  tude 

R2  - 

0  (zero  suppress) 

RO  "  next  available 

output 

SCBTMG 

R2  » 

nonzero  (no  zero  suppress) 

address 

CALL 

SCBTwn 

R3-R5  preserved 
R1-H2  destroyed 

(continued  on  neKt  page) 
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Table  9-4  (Cont.) 
Output  Data  Conveislon  Routines  Summary 


Routine  Name/ 

Mnemonic 

Input 

Arguments  and  Call  Statement 

Outputs 

General  Pur(.ose 

.0. 

output  address 

Conver^ed  number  at  output 

Binary  to 

Rl  - 

binary  value 

address 

ASCII 

R2  - 

conversion  parameters; 

RO  •  next  available  output 

SCBTA 

bits  O-""!  radix  (2.  to  16.) 

address 
P3-R5  preserved 

hit  8:   -  ;  =  unsigned  value 

RI-r;.  destroyed 

•  I  •  signed  value 

bit  9:   -  0  •  zero  suppress 

-  1  ■  no  zero 

suppress 

bit  10:  •  1,  replace  leading 

zeroes  with  blanks. 

•  0,  do  not  replace 

leading  zeroes  with 

blanks. 

bl'-.s  11-lS:  field  width 

(vaUe  1-32) 

CALL 

SCBTA 

Hr-^'.t-SO    to 

RO  • 

output  address 

Converted  number  at  output 

k{,^il 

Rl  - 

padlx-50  w<^rJ 

address 

$C5VA 

CALL 

SC5TA 

RO  <•  next  available  output 

address 
R3-R5  not  used 
R1-R2  destroyed 

Table  9-5 
Cjput  Formatting  Routines  Summary 


Routine  N->me/ 

Mnemonic 

Input  Arguments  and  Call  Statement 

Outputs 

Upper  Case 

RO  - 

input  address 

Converted  text  at  output 

Text 

Rl  - 

output  address 

address 

SCVTUC 

R2  - 

number  input  bytes 

S3-R5  not  used 

(cannot  be  zero) 

R2  destroyed 

CALL 

SCVTUC 

RO-Rl  left  pointing  to  the 

character  following  the 
string. 

Date  String 

RO  - 

output  address 

Converted  date  string  at 

Conversion 

Rl  • 

input  address 

output  address 

SDAT 

CALL 

SDAT 

RO  -  next  available  output 

iddress 
Rl  •  address  of  next  Input 

word 
R3-H5  preserved 
R2  destroyed 

(continued  on  next  page) 
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Table  9-5  (Conf . ) 
Ouput  Formatting  Rout  nes  Summary 


Routine  Narae/ 

Mnemon Ic 

Input  Arguments  and  Call  Statement 

1 

Outputs 

Time  Con- 

■ 
RO  •  output  address 

Converted  time  string  at 

version 

Rl  •  Input  address 

output  adJress 

,-TrM 

R2  '  para.^eter  count  i 

HO  •  next  available  output 

«  0  or  1,  hout  (HH) 

address 

"  2,  hour:minute  (HH:MM) 

Rl  •  address  of  next  Input 

"  3,  hour  :ininute:8econ<l 

word 

(HH:MM:SS) 

B3-R5  preserved 

"  4  or  5,  hour :mtnute:9econd . 

RO-Rl  updated 

tenth  of  second  (HH:MM!SS.S) 

R2  destroyed 

CALL  iTIM 

Edit  M' ssaqe 

Define  ASCII  Input  string 

Converted/formatted  data  In 

SEDMSG 

directives  In  the  form: 

output  block 

RO  ■  address  of  last  byte 

%1 

In  output  block  whlr^ 

%nl 

Is  a  zero 

IVl 

Rl  -  number  of  bytes  In 

output  block 
R2  -  address  of  next  argu- 

where n  •  optional  decimal  repeat 

ment  In  argument  block 

count;  V  specifies  an  optional 

Rj-R5  preserved 

value  to  be  used  as  a  repeat 

count;  and  1  ■  one  of  the 

fol lowing: 

A  ■  ASCII  string  transfer 

B  -  Binary  byte  to  octal  conver- 

s  ton 

D  •  Binary  to  signed  decimal 

conversion 

E  «  Extended  ASCII  strln-j  transfer 

F  '  Form  control  insertion 

I  .  ASCIZ  address 

M  «  Binary  to  decimal  magnitude 

conversion,  zero  suppression 

N  "  New  1 ine  insert  ion 

0  •  Binary  to  signed  octal  conver- 

sion 

-  Binary  t:.  octal  magnitude  con- 

version, no  zero  suppression 

convers Ion 

0  •  Binary  to  octal  magnitude  con- 

version, zero  suppteislon 

R  "  Radlx-50  t'j  ASCII  co'^.verslon 

S  -  Space  Insertion 

T  »  Double-precision  binary  to 

decimal  conversion 

U  •  Binary  to  double-precision 

decimal  conversion,  no  zero 

suppress  Ion 

X  »  File  name  conversion 

Y  »  Date  conversion 

Z  "  Time  conversion 

'  »  Deflno  fixed  length  byte  fieU 

>  =  Locate  field  mark 

(continued  on  next  page) 
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Table  9-5  (Cont.) 
Output  Formatting  Routines  Summary 


Rout  in >  Name/ 

Mnemonic 

Input  Arguments  and  Call  Statement 

Outputs 

Set  up  argument  and  output  blick 

RO  «  output  address 

Rl  »  input  string  address 

R2  ■  argument  block  address 

CALL  SEDMSG 

Table  9-6 
Dynamic  Memory  Management  Routines  Summary 


Rout  i ne  Name/ 
Mnemonic 

Input  Arguments  anci  Call  Statement 

Outputs 

Initialize 
Dynamic 
Memory 
$  I N I  DM 

Include  FREEHD:  .BLK.,  ?  in  data 
sect  ion 

RO  =  free  memory  listhead  address 
CALL  SINIDM 

RO  =  task's  first  address 
Rl  =  free  pool  first  address 
R2  =  size  memory  pool 
R3-R5  not  used 

Request  Core 

Block 

$ROCB 

Ru  =  free  memory  listhead  address 
Rl  =  byte  size  of  block 
CALL  SROCB 

Successful  ; 

RO  =  block  memory  address 

Rl  =  actual  size  of  block 

C  =  clear 

Unsuccessful : 

C  =  set 

R3-R5  preserved 

R2  destroyed 

Release  Core 

Block 

SRLCB 

RO  =  free  memory  listhead  address 
Rl  -  byte  size  of  block 
R2  =  block  memory  address 

Released  block 
R3-R5  preserved 
RO  unchanged 
R1-R2  destroyed 

Table  9-7 
Virtual  Memory  flanagement  Routines  Summary 


Routine  Name/ 

Mnemonic 

Input  Arguments  and  Call  Statement 

Outputs 

Ini  tialize 

Define  SFRHD  block  with  first 

Successful  : 

Virtual 

address  of  free  memory 

C  =  clear  and  RO  =  0 

Memory 

Define  t  global  symbols:  WSKLUN 

Failure 

S  I N  1 VM 

(work  file  LUN) ;  WSKEXT  (work 

C  '  set  and 

file  extension  size);  NSMPAG 

RO  '  -2,  file  not  opened 

(fast  page  search  ^'96  count) 

RO  =  -1 ,  file  not  marked 

RO  =  fre"  memory  highest  address 

R3-R5  preserved 

CALL  SINIVM 

Original  content  R0-R2 
destroyed 

(continued  on  next  page) 
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Table  9-7  (Coit.) 
Virtual  Memory  management  Routines  Summary 


Routine  Name/ 

Mnemonic 

Input  Arguments  and  Cal»  Statement 

Outputs 

Allocate 

Rl  =■  byte  olze  of  requested  block 

Successful : 

Block 

CALL  SALBLK 

RO  "  block  memory  address 

SALBLK 

Unsuccessful : 

User's  SERMSG  routine  Is  called 

R3-R5  preserved 

R0-R2  destroyed 

Get  Core 

Rl  •  byte  size  of  requested  block 

Successful : 

SOTCOR 

CALLSGTCOR 

RO  •  block  memory  address 

C  -  clear 

Unsuccessful : 

C  -  set 

R3-R5  preserved 

Extend 

Rl  =  byte  size  of  requested  block 

Successful : 

Task 

CALL  SEXTSK 

Rl  •  actual  extension  size 

SEXTSK 

C  "  clear 

fal  lure: 

C  -  set 

R2-R5  preserved 

Write 

R2  -  memory  address  of  page 

Successful : 

Page 

CALL  SWRPAG 

C  "  clear 

SWRPAG 

Unsuccessful : 

User's  SERMSG  routine  Is  called 

R0-R2  preserved 

Allocate 

Rl  »  byte  size  of  requested  block 

Successful : 

Virtual 

CALL  SALVRT 

RO  »  allocated  block  memory 

Memory 

address 

SALVRT 

Rl  •  allocated  block  disk 

address 
Unsuccessful : 

User's  SERMSG  routine  Is  called 
R3-R5  preserved 
R2  destroyed 

Allocate 

Define  NSOLGH  «  «  512. 

RO  "  block  memory  addres* 

Small 

Rl  »  size  of  requested  page  block: 

Rl  •  block  vlrcual  address 

Virtual 

«  0,  for  l<rge  block  allocation 

R3-R5  preserved 

Block 

on  first  call  to  SALSVB 

R2  destroyed 

SALSVB 

=  a  value  less  than  or  equal  to 
512  (10)  bytes  for  small  page 
al  location 
CALL  SALSVB 

Convert  and 

Rl  •  virtual  address 

Successful : 

Lock  Page 

CALL  SCVLOK 

RO  "  memory  address 

SCVLOK 

Rl  ■  virtual  address 

C  "  clear 

Unsuccessful : 

C  -  set 

R2-R5  preserved 

(continued  on  next  page) 
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Table  9-7  (Cont.) 
Virtual  Meir.ory  Management  Routines  Summary 


Routine  Name/ 
Mnemon  ic 

Input  Arguments 

and  Cal 1  Statement 

Outputs 

Convert  Virtual 
to  Real  Address 
SCVRL 

Rl  = 
CALL 

vi  rtual 
SCVRL 

address 

RO  "  memory  address 
R3-R5  preserved 
Rl  unchanged 
R2  destroyed 

Read  Page 
SRDPAG 

RO  " 
CALL 

r-ge  dl 
SRDPAG 

3k  address 

Successful ; 

C  »  clear 

Unsuccessful  . 

User's  SERMSG  routine  is  call 

R0-R2  preserved 

ed 

Find  Page 
SFNDPG 

Rl  = 
CALL 

page  virtual  address 
SFNDPG 

Page  found: 

RO  -  block  memory  address 

C  "  clear 

Page  not  found: 

C  -  set 

Wr  i  to-marked 

Page 

SWRMPG 

Rl  « 

CALL 

vi  rtual 
SWRMPG 

address  in  page 

C  •  clear,  page  wrlte-marked 
C  •  set,  page  not  found 
R0-R2  preserved 

Lock  Page 
SLCKPG 

Rl  » 
CALL 

vi  rtual 
SLCKPG 

addres:!  in  page 

C  «  clear,  page  locked 
C  -  set,  page  not  found 
R0-R2  preserved 

Unlock  Page 
SUNLPG 

Rl  = 
CALL 

vi  rtual 
SUNLPG 

address  in  page 

C  »  clear,  page  unlocked 
C  "  set,  page  not  found 
R0-R2  preserved 
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SYSTEM  REFERENCE  BIBLIOGRAPHY 


This  bibliography  identifies  manuals  that  contain  descriptions  of 
additioi.al  routines  available  to  users  of  the  IAS/RSX-11  system 
libraries. 

First  level  entries  are  manual  titles.  Second  level  entries  are 
functional  headings  indicating  the  types  of  services  described  in  the 
respective  manual. 

IAS  EXECUTIVE  REFERENCE  MANUAL  (VOLUMES  I  AND  II) 

Task  Execution  Control  Directives 

Informational  Directives 

Event-associated  Directives 

Trap-associated  Directives 

I/O  Related  Directives 

Task  Status  Control  Directives 

lAS/RSX-llD  DEVICE  HANDLERS  REFERENCE  MANUAL 

Laboratory  and  Industrial  I/O  Routines 

IAS/RSX-11  I/O  OPERATIONS  REFERENCE  MANUAL 

I/O  Preparation  Services 

File  Processing  Services 

Pile  Control  Routines 

File  Structuring  Services 

Command-line  Processing  Services 

Parsing  Services 

Spooling  Services 

RSX-llD  EXECUTIVE  REFERENCE  MANUAL 

Task  Execution  Control  Directives 

Informational  Directives 

Event-associated  Directives 

Trap-associated  Directives 

I/O  Related  Directives 

Task  Status  Control  Directives 
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RSX-llM  EXECUTIVE  REFERENCE  MANUAL 

Task  Execution  Control 

Task  Status  Control 

Event-associated  Services 

Trap-associated  Services 

I/O  and  Intertask  Communication 

Memory  Management  Services 


RSX-llM  I/O  DRIVERS  REFERENCE  MANUAL 

Laboratory  and  Industrial  I/O  Routines 
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UNIVERSAL  LIBRARY  ACCESS 


On  most  RSX-llM  systems,  the  usar  can  create  a  universal  library  to 
store  files  of  a  similar  type.  The  LBR  utility  creates  the  universal 
library  file  •  ''■h  a  file  type  .  ULB .  By  means  of  the  LBR  utility,  the 
user  can  subsfc    ntly  insert  files  as  modules  in  the  library.^ 

To  access  a  module  of  a  universal  library,  a  program  can  call  the  SULA 
routine,  which  establishes  the  necessary  conditions  for  access  (read 
onl/).  The  $ULA  routine  firs",  calls  an  initializing  routine,  $ULAIN, 
to  validate  that  the  library  file  is  in  the  correct  format  and  to 
obtain  the  needed  information  from  the  library  header.  $ULA  then 
calls  a  second  routine,  SULAFD,  to  read  the  module  header,  tc  position 
llbary  file  pointers  to  the  beginning  of  the  module,  and  to  establish 
the  necessary  FDB  locations  for  the  File  Control  System  (FCS).2  Once 
the  necessary  FDB  locations  are  established,  the  program  can  access 
the  module  as  if  i  ♦;  were  a  separate  file.  That  is,  the  program  can 
perform  GETS  operations  in  move  mode  for  each  record  in  the  module. 

To  call  the  S'JLA  routine,  supply  the  following  data. 

•  In  RC,  the  address  of  the  universal  library  FDB.  The  library 
file  must  already  be  open  for  read  access. 

•  In  Rl,  the  --Jdress  of  a  42(8)-word  buffer.  The  first  two 
words  of  the  buffer  must  contain  the  name  (in  Radix-SO  format) 
of  the  module  to  be  accessed.  Into  the  remaining 
100  (8) =64  (10)  bytes  SULA  will  put  a  copy  of  the  module  header 
from  the  library.  Initialize  the  FDRCSA  arguments  urba  and 
urbs  (FDB  offsets  F.URBD  and  and  F.URBD-f2)  In  the  FDB  for  thf 
library  file.  The  SULA  routine  saves  the  arguments,  uses  the 
space  for  storing  module  header  information,  and  restores  the 
values  before  returning  control  to  the  calling  program. 

The  SULA  routine  outputs  the  following  data: 

■  t 

•  P":  is  unchanged. 

•  Rl  is  unchanged.  The  SULA  routine  fills  in  the  40-word  buffer 
with  a  copy  of  the  header  for  the  module  accessed. 


1.  For  more  information  on  universal  libraries,  refer  to  the 
description  of  the  LBR  utility  in  Chapter  14  of  the  RSX-11  Utilities 
Manual . 


2.  See  the  IAS/RSX-1 1  I/O  Operations  Reference  Manual  for   information 
on  FCS  and  use  of  FDB  locationsT 
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•  The  offset  F.FFBY  of  ^he  library  file  FDS  contains  the   number 
of  the  next  available  byte  past  the  end  of  the  module. 

•  The  offset  F.ERR  of  the  library   file   FDB   hos   the   standard 
interpretations  except  for  the  followinq  special  meaninas. 

•  The  symbol  lE.BHD  means  either  FILE   NOT   A   UNIVERSAL 
LIBRARY  or  BAD  LIBRARY  HEAnER. 

•  The  symbol  lE.NSF  means  NO  SUCH  MODULE. 

•  The  C  bit  jet  indicates  an  error. 

To  properly  use  the  SULA  routine,  follow  the  coding  sequence  below. 


OPENS 


store  f 


CALL 


GET? 


restore 


RO 


;OPEN  UNIV  LIB  FILE 


rst  seven  words  of  library  FDB 


ULA 


.•access  module  in  move  mode  only 


first  seven  words  of  librar 


y  FDB 


CLOSES  RO  or  invoke  SULA  again 


Note  that  the  program  must  open  the  library  file  for  read-only  access'. 
(To  change  a  module  in  the  universal  library,  use  the  LBP  utility  ) 
The  program  must  save  the  first  seven  words  of  the  library  file  FDB 
tfriVfLJtl^''"^  ""^^  SULA  routine  for  the  first  time.  The  SULA  routine 
modifies  these  words  during  processing  but  their  original  values  are 
necessary  either  to  access  another  module  or  to  ensure  that  the 
tt.rr^^''^  fj^  ^^  properly  closed.  The  program  must  restore  the  seven 
words  after  accessing  a  module  ard  before  accessing  another  module  or 
before  closing  the  library  file. 
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$ALBLK  (Allocat 

$ALSVB  (Allocat 

block) ,  8-1 

$ALVRT    (Allocat 

memory) ,    8-16 

ASCII  conversio 

See  ASCII  num 

ASCII  number  co 

ASCII  to  Radi 

4-6 
ASCII  with  bl 

Radix-50 
decimal  to  bi 

4-4 

decimal  to  bi 

double-wo 

4-1 

octal  to  bina 

octal  to  bina 

(.0D2CT) , 


e  block) ,  8-9 

e  small  virtual 

8 

e  virtual , 

n, 

ber  conversion 
nversion , 
x-50  ($CAT5) , 

anks  to 
($CAT5B) ,  4-8 
nary  ($CDTB) , 

nary 

rd  (.DD2CT), 

ry  (SCOTB) ,  4-5 
ry  double-word 
4-2 


to  signed 
3 

purpose  binary 
5-10 
byte  to  octal )  , 


Binary  conversirm, 
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